@geastack/compiler 1.0.15

package/dist/semantics/normalize/implicit-arguments-tuple.js

@@ -0,0 +1,197 @@
+import ts from 'typescript';
+import { disjointUnionTypeOf, joinOfWrites } from './derived-expression-type.js';
+import { enclosingArgumentsFunction, implicitArgumentsSlotOf, isArgumentsObjectIdentifier } from './implicit-arguments.js';
+/**
+ * Whether `args[index]` is a final magic-`arguments` spread into a callee
+ * with a static convention and no rest formal.
+ *
+ * Such a spread fills the callee's formals POSITIONALLY: the frame's values
+ * land at `0..n-1` exactly as a written argument list would, and a formal no
+ * value reaches binds `undefined` the way an omitted argument does. It must be
+ * the LAST argument, or a later written argument would land at a position only
+ * the frame's runtime length knows; the callee must declare no rest formal, or
+ * the split between named formals and the packed tail would be that same
+ * runtime fact. `convention === null` is a callee with no static convention at
+ * all, which states nothing to fill positionally.
+ *
+ * Shared by the census (which admits the spread as a read-only use of the
+ * frame) and the producer (which mints one read per position): the two
+ * deciding separately is how an admitted use would meet a refused expansion.
+ */
+export const isFixedArgumentsSpreadAt = (checker, args, index, convention) => {
+    const argument = args[index];
+    return !!(argument &&
+        ts.isSpreadElement(argument) &&
+        index === args.length - 1 &&
+        convention !== null &&
+        convention.restFrom === null &&
+        isArgumentsObjectIdentifier(argument.expression, checker));
+};
+/**
+ * The census-side convention of the callee a `...arguments` spread reaches:
+ * the checker's resolved signature, with its rest formal where the producer's
+ * `SelectedSignature` finds one (a parameter written with `...`). A callee
+ * that is itself an `arguments` shim carries the checker's phantom rest slot,
+ * which has no declaration to spell `...` but is a rest formal all the same
+ * (`structural-parts.ts` publishes it as one), so a shim-to-shim spread is not
+ * a fixed fill. No declaration at all is the producer's `selected === null`.
+ */
+const spreadConventionAt = (checker, call) => {
+    const signature = checker.getResolvedSignature(call);
+    if (!signature?.declaration)
+        return null;
+    const written = signature.getParameters().findIndex((parameter) => {
+        const declaration = parameter.valueDeclaration;
+        return declaration !== undefined && ts.isParameter(declaration) && declaration.dotDotDotToken !== undefined;
+    });
+    return { restFrom: written >= 0 ? written : (implicitArgumentsSlotOf(signature)?.ordinal ?? null) };
+};
+/** The fixed position a numeric element read names, or `null` for a position only known at run time. */
+const fixedPositionOf = (checker, access) => {
+    const key = checker.getTypeAtLocation(access.argumentExpression);
+    const value = key.isNumberLiteral()
+        ? key.value
+        : key.isStringLiteral() && key.value !== '' && String(Number(key.value)) === key.value
+            ? Number(key.value)
+            : null;
+    return value !== null && Number.isInteger(value) && value >= 0 ? value : null;
+};
+/**
+ * How one use of the frame reads it, with the expression that reads it, or
+ * `null` when the object escapes the reads this fact can describe.
+ */
+const useOf = (checker, use) => {
+    const access = use.parent;
+    if (ts.isElementAccessExpression(access) && access.expression === use)
+        return { read: fixedPositionOf(checker, access) === null ? 'indexed' : 'fixed', access };
+    if (ts.isPropertyAccessExpression(access) && access.expression === use && access.name.text === 'length')
+        return { read: 'indexed', access };
+    if (ts.isSpreadElement(access) && access.expression === use) {
+        const call = access.parent;
+        if ((ts.isCallExpression(call) || ts.isNewExpression(call)) && call.arguments) {
+            const args = call.arguments;
+            if (isFixedArgumentsSpreadAt(checker, args, args.indexOf(access), spreadConventionAt(checker, call)))
+                return { read: 'fixed', access };
+        }
+    }
+    return null;
+};
+/**
+ * The frame fact for one owner, from its uses and its closed callers.
+ *
+ * Never inferred from only the callers that happened to type: one caller
+ * whose argument states nothing refuses the whole frame, because the frame is
+ * what EVERY caller fills.
+ */
+export const inferImplicitArgumentsTuple = (evidence) => {
+    const { checker, owner, slot, uses } = evidence;
+    let indexed = slot.ordinal > 0;
+    for (const use of uses) {
+        // A lexical arguments capture needs a frame identity shared with its
+        // outer function; a local ordinal alone cannot establish that identity.
+        for (let parent = use.parent; parent !== owner; parent = parent.parent) {
+            if (ts.isArrowFunction(parent))
+                return { refused: 'implicit-arguments-lexical-capture' };
+        }
+        const reading = useOf(checker, use);
+        if (reading === null)
+            return { refused: 'implicit-arguments-object-escapes' };
+        if (reading.read === 'indexed')
+            indexed = true;
+        // The shared write inventory already includes parenthesized targets,
+        // destructuring, updates, loops and deletes. Do not invent a second
+        // assignment classifier for this one binding.
+        if (evidence.isWritten(use) || evidence.isWritten(reading.access))
+            return { refused: 'implicit-arguments-mutated' };
+    }
+    if (evidence.calls.length === 0)
+        return { refused: 'implicit-arguments-no-callers' };
+    const passed = [];
+    const positions = [];
+    let required = Number.POSITIVE_INFINITY;
+    let readsOwnElement = false;
+    for (const call of evidence.calls) {
+        const args = evidence.argumentsOf(call);
+        if (args.length < slot.ordinal)
+            return { refused: 'implicit-arguments-omitted-prefix' };
+        if (args.some(ts.isSpreadElement))
+            return { refused: 'implicit-arguments-spread-caller' };
+        required = Math.min(required, args.length);
+        for (const [position, argument] of args.entries()) {
+            // This back edge only selects an existing element, or undefined.
+            // Solve T = join(external writes, T | undefined) from independent
+            // seeds, never from the prior round's answer to its own cycle.
+            if (evidence.isRecursiveCall(call) &&
+                ts.isElementAccessExpression(argument) &&
+                isArgumentsObjectIdentifier(argument.expression, checker) &&
+                enclosingArgumentsFunction(argument.expression) === owner &&
+                (checker.getTypeAtLocation(argument.argumentExpression).flags & ts.TypeFlags.NumberLike) !== 0) {
+                readsOwnElement = true;
+                continue;
+            }
+            const type = evidence.argumentTypeOf(argument);
+            if (!type)
+                return { refused: 'implicit-arguments-unresolved-caller', evidence: argument };
+            const widened = type.isLiteral() ? checker.getBaseTypeOfLiteralType(type) : type;
+            passed.push(widened);
+            (positions[position] ??= []).push(widened);
+        }
+    }
+    if (passed.length === 0)
+        return { refused: 'implicit-arguments-no-element-evidence' };
+    if (!indexed && !readsOwnElement) {
+        // Phantom ordinal 0, so the owner declares no parameter to state a bound:
+        // each position is exactly the join of what its callers write there.
+        const elements = [];
+        for (const [position, written] of Array.from(positions, (entry) => entry ?? []).entries()) {
+            const element = written.length > 0 ? (joinOfWrites(checker, written) ?? disjointUnionTypeOf(checker, written)) : null;
+            if (!element)
+                return { refused: 'implicit-arguments-disjoint-position' };
+            elements[position] = element;
+        }
+        return { tuple: { frame: 'tuple', elements, required: Math.min(required, elements.length) } };
+    }
+    // An annotation can supply a common upper bound absent from the
+    // observed subclasses. It is only a candidate: every supplied position,
+    // including extra arguments, must fit it through the same write join.
+    const element = joinOfWrites(checker, passed) ??
+        evidence.statedElements.map((stated) => joinOfWrites(checker, [...passed, stated])).find((joined) => joined !== null) ??
+        disjointUnionTypeOf(checker, passed);
+    return element
+        ? { tuple: { frame: 'array', element: readsOwnElement ? checker.getNullableType(element, ts.TypeFlags.Undefined) : element } }
+        : { refused: 'implicit-arguments-disjoint-elements' };
+};
+/** One element read's type out of a settled frame: `index === null` is a position only known at run time. */
+export const implicitArgumentsElementTypeOf = (checker, tuple, index) => {
+    if (tuple.frame === 'array')
+        return checker.getNullableType(tuple.element, ts.TypeFlags.Undefined);
+    // A tuple frame is only ever settled for a body whose reads all name a fixed position.
+    if (index === null)
+        return null;
+    const element = tuple.elements[index];
+    if (element === undefined)
+        return checker.getUndefinedType();
+    return index >= tuple.required ? checker.getNullableType(element, ts.TypeFlags.Undefined) : element;
+};
+/** Every numeric read consumes the owning frame's fact, including reads published to sibling censuses. */
+export const implicitArgumentsReadTypeAt = (checker, node, tupleAt) => {
+    if (!ts.isElementAccessExpression(node) || !isArgumentsObjectIdentifier(node.expression, checker))
+        return null;
+    const key = checker.getTypeAtLocation(node.argumentExpression);
+    const numericKey = (key.flags & ts.TypeFlags.NumberLike) !== 0 ||
+        (key.isStringLiteral() && key.value !== '' && String(Number(key.value)) === key.value && Number.isInteger(Number(key.value)));
+    if (!numericKey)
+        return null;
+    const owner = enclosingArgumentsFunction(node.expression);
+    const tuple = owner ? tupleAt(owner) : null;
+    return tuple ? implicitArgumentsElementTypeOf(checker, tuple, fixedPositionOf(checker, node)) : null;
+};
+/** Two settled frame facts state the same frame: the fixpoint's identity test for this query. */
+export const sameImplicitArgumentsTuple = (left, right) => {
+    if (left.frame === 'array' || right.frame === 'array') {
+        return left.frame === 'array' && right.frame === 'array' && left.element === right.element;
+    }
+    return (left.required === right.required &&
+        left.elements.length === right.elements.length &&
+        left.elements.every((element, index) => element === right.elements[index]));
+};

package/dist/semantics/normalize/implicit-arguments.d.ts

@@ -0,0 +1,11 @@
+import ts from 'typescript';
+/** The checker-synthesized trailing slot, keyed by its owning signature. */
+export interface ImplicitArgumentsSlot {
+    readonly ordinal: number;
+    readonly symbol: ts.Symbol;
+}
+export declare const implicitArgumentsSlotOf: (signature: ts.Signature) => ImplicitArgumentsSlot | null;
+export declare const isArgumentsObjectIdentifier: (node: ts.Node, checker: ts.TypeChecker) => node is ts.Identifier;
+export declare const isBodiedSignatureDeclaration: (node: ts.Node) => node is ts.FunctionLikeDeclaration;
+export declare const enclosingArgumentsFunction: (node: ts.Node) => ts.FunctionLikeDeclaration | null;
+export declare const argumentsObjectPhantomOrdinalAt: (node: ts.Node, checker: ts.TypeChecker) => number | null;

package/dist/semantics/normalize/implicit-arguments.js

@@ -0,0 +1,39 @@
+import ts from 'typescript';
+export const implicitArgumentsSlotOf = (signature) => {
+    const parameters = signature.getParameters();
+    const symbol = parameters[parameters.length - 1];
+    if (!symbol || symbol.valueDeclaration || symbol.declarations?.length)
+        return null;
+    if (parameters.slice(0, -1).some((parameter) => !parameter.valueDeclaration && !parameter.declarations?.length))
+        return null;
+    return { ordinal: parameters.length - 1, symbol };
+};
+export const isArgumentsObjectIdentifier = (node, checker) => {
+    if (!ts.isIdentifier(node) || node.text !== 'arguments')
+        return false;
+    const symbol = checker.getSymbolAtLocation(node);
+    return !!symbol && symbol.valueDeclaration === undefined && (symbol.declarations?.length ?? 0) === 0;
+};
+export const isBodiedSignatureDeclaration = (node) => ts.isFunctionDeclaration(node) ||
+    ts.isFunctionExpression(node) ||
+    ts.isArrowFunction(node) ||
+    ts.isMethodDeclaration(node) ||
+    ts.isConstructorDeclaration(node) ||
+    ts.isGetAccessorDeclaration(node) ||
+    ts.isSetAccessorDeclaration(node);
+export const enclosingArgumentsFunction = (node) => {
+    for (let parent = node.parent; parent; parent = parent.parent) {
+        if (ts.isArrowFunction(parent))
+            continue;
+        if (isBodiedSignatureDeclaration(parent))
+            return parent;
+    }
+    return null;
+};
+export const argumentsObjectPhantomOrdinalAt = (node, checker) => {
+    if (!isArgumentsObjectIdentifier(node, checker))
+        return null;
+    const owner = enclosingArgumentsFunction(node);
+    const signature = owner ? checker.getSignatureFromDeclaration(owner) : undefined;
+    return signature ? (implicitArgumentsSlotOf(signature)?.ordinal ?? null) : null;
+};

package/dist/semantics/normalize/instantiation.d.ts

@@ -0,0 +1,73 @@
+import ts from 'typescript';
+import type { ProgramReachability } from './reachability.js';
+/**
+ * Which type a type parameter is actually bound to, program-wide.
+ *
+ * A type parameter has no carrier. `T` is not a thing a value can be stored as
+ * -- it is a hole an instantiation fills -- so representation refuses it, and
+ * that refusal is correct. What is missing is the instantiation: a generic
+ * function's body is compiled once here, with `T` still a hole, when the
+ * language says the body exists once *per instantiation*.
+ *
+ * Full monomorphization compiles a generic body once per distinct type-argument
+ * tuple, minting a separate identity for each copy. This census is the first
+ * half of that, and it answers the case that turns out to dominate real
+ * programs: a generic instantiated at exactly ONE type across the whole program.
+ * A framework's `mount<RootComponent extends Component>` is instantiated once,
+ * by the one application that calls it; a `Store<State>` is instantiated by the
+ * one state type the app declares. When the binding is unique there is nothing
+ * to duplicate -- the body has one meaning -- so substituting it is exact rather
+ * than an approximation, and no second identity is needed.
+ *
+ * When a parameter is bound to two different types, this census says so by
+ * answering `null`, and representation refuses exactly as it did before. That
+ * refusal is then honest about what is missing -- body duplication -- instead of
+ * being a blanket refusal of every generic in the program.
+ *
+ * Erasing to the constraint instead was considered and is wrong here. Java
+ * erases `T extends Component` to `Component` because every reference is a
+ * pointer to a heap object with a shared header; a `class-ref` carrier in this
+ * compiler is a flat struct with the fields of exactly that class, so "erase to
+ * the base" would hand a caller a struct of the wrong size and shape. Erasure
+ * is not a weaker version of monomorphization here; it is a different, unsound
+ * thing.
+ *
+ * One more source counts as a binding, at lower priority than a genuine one:
+ * a type parameter's OWN constraint, which is what a caller who never
+ * supplies an explicit argument resolves to (`mount<RootComponent extends
+ * Component>` binds `Component`'s parameter to `GeaElement` for every
+ * program, since every program calls `mount`). That default is recorded
+ * separately from a genuine call/type-reference site and consulted only when
+ * NO genuine site exists anywhere reachable -- so a program with one real
+ * instantiation resolves to that real one despite the ever-present default,
+ * and a program with none (most apps reach `Component` only through
+ * `ReactiveComponent<E> extends Component<E>`, itself parameterized) still
+ * resolves, instead of coming up empty. See `censusInstantiations`'s
+ * `bindings` map and the `unique` loop for the two-bucket mechanics.
+ */
+export interface InstantiationCensus {
+    /**
+     * The one type this parameter is bound to everywhere, or `null` when it is
+     * bound to none or to more than one.
+     */
+    readonly bindingOf: (declaration: ts.Declaration) => ts.Type | null;
+}
+/** A census that knows nothing, for a caller that has not run the walk. */
+export declare const emptyInstantiationCensus: InstantiationCensus;
+/**
+ * Every instantiation the program makes, collected before anything is
+ * normalized.
+ *
+ * Two sources, and they are different questions. A *call* instantiates a
+ * generic signature, and the checker has already inferred its arguments -- so
+ * the resolved signature paired against the generic one it came from is the
+ * whole answer. A *type reference* instantiates a generic declaration directly,
+ * including through a default (`class Home extends Component` is
+ * `Component<unknown>`), and there the type's own arguments are the answer with
+ * nothing to unify.
+ *
+ * The walk covers the program's own files, not its declaration files: an
+ * instantiation is something a program does, and a `.d.ts` states types without
+ * ever performing one.
+ */
+export declare const censusInstantiations: (checker: ts.TypeChecker, sourceFiles: readonly ts.SourceFile[], reachable: ProgramReachability) => InstantiationCensus;