@geastack/compiler 1.0.15

package/dist/semantics/prototype-reparenting.js

@@ -0,0 +1,317 @@
+import ts from 'typescript';
+import { isGlobalObjectConstructor, isStandardInterfaceType } from './normalize/derived-expression-type.js';
+/** `C.prototype`, with `C` returned. */
+const prototypeOwnerOf = (expression) => ts.isPropertyAccessExpression(expression) && expression.name.text === 'prototype' ? expression.expression : null;
+/** The program class a constructor-typed value denotes -- the static side only, whose type is the class symbol's own value type. */
+const classOfConstructorValue = (checker, expression) => {
+    const type = checker.getTypeAtLocation(expression);
+    const symbol = type.getSymbol();
+    if (!symbol || (symbol.flags & ts.SymbolFlags.Class) === 0 || checker.getTypeOfSymbol(symbol) !== type)
+        return null;
+    const declarations = (symbol.declarations ?? []).filter((declaration) => ts.isClassLike(declaration));
+    if (declarations.length !== 1)
+        return null;
+    const declaration = declarations[0];
+    return declaration.getSourceFile().isDeclarationFile ? null : declaration;
+};
+/** `B` and every class it extends, nearest first, or `null` when one of them is not a class this program compiles. */
+const programClassChainOf = (checker, base) => {
+    const chain = [];
+    let current = base;
+    while (current) {
+        if (chain.includes(current) || current.getSourceFile().isDeclarationFile)
+            return null;
+        chain.push(current);
+        const symbol = checker.getSymbolAtLocation(current.name ?? current);
+        const declared = symbol ? checker.getDeclaredTypeOfSymbol(symbol) : undefined;
+        const bases = declared?.isClassOrInterface() ? checker.getBaseTypes(declared) : [];
+        if (bases.length === 0)
+            return chain;
+        if (bases.length !== 1)
+            return null;
+        const next = bases[0].getSymbol()?.declarations?.find((candidate) => ts.isClassLike(candidate));
+        if (!next || !ts.isClassLike(next))
+            return null;
+        current = next;
+    }
+    return chain;
+};
+const memberNameOf = (member) => member.name && (ts.isIdentifier(member.name) || ts.isStringLiteral(member.name) || ts.isPrivateIdentifier(member.name))
+    ? member.name.text
+    : null;
+const isStatic = (member) => (ts.getCombinedModifierFlags(member) & ts.ModifierFlags.Static) !== 0;
+/**
+ * Whether a `C` instance behaves as a `B` instance would through every member
+ * `C` does not answer itself.
+ *
+ * `C`'s construction never runs `B`'s constructor, so in the language the
+ * instance has none of `B`'s own state: a `B` field read on it is
+ * `undefined`, a `#private` read throws. The compiled instance carries `B`'s
+ * layout as its base subobject, default-initialized. The two agree exactly
+ * when nothing reads that state through a `C` instance: `B` (and each class
+ * it extends) declares no public instance field, and every prototype member
+ * `C` does not override reaches `this` only to look up a method or accessor
+ * -- which dispatch resolves to `C`'s own when `C` declares it, and to one
+ * this same rule checked otherwise. `super` in such a member names a
+ * specific ancestor's member regardless of what `C` overrides, so it is
+ * refused rather than followed.
+ */
+const reparentingIsSound = (derived, chain) => {
+    const overridden = new Set(derived.members.flatMap((member) => (isStatic(member) ? [] : [memberNameOf(member)])));
+    const behaviours = new Set();
+    for (const owner of chain) {
+        for (const member of owner.members) {
+            if (isStatic(member))
+                continue;
+            if (ts.isConstructorDeclaration(member)) {
+                const exposed = member.parameters.some((parameter) => ts.isParameterPropertyDeclaration(parameter, member) &&
+                    (ts.getCombinedModifierFlags(parameter) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected)) === 0);
+                if (exposed)
+                    return false;
+                continue;
+            }
+            if (ts.isPropertyDeclaration(member)) {
+                const hidden = ts.isPrivateIdentifier(member.name) ||
+                    (ts.getCombinedModifierFlags(member) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected)) !== 0;
+                if (!hidden)
+                    return false;
+                continue;
+            }
+            const name = memberNameOf(member);
+            if (name !== null && (ts.isMethodDeclaration(member) || ts.isAccessor(member)) && !ts.isPrivateIdentifier(member.name))
+                behaviours.add(name);
+        }
+    }
+    const readsOnlyBehaviour = (body) => {
+        let sound = true;
+        const visit = (node) => {
+            if (!sound)
+                return;
+            // A non-arrow function binds its own `this`.
+            if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isClassLike(node))
+                return;
+            if (node.kind === ts.SyntaxKind.SuperKeyword) {
+                sound = false;
+                return;
+            }
+            if (node.kind === ts.SyntaxKind.ThisKeyword) {
+                const access = node.parent;
+                sound =
+                    ts.isPropertyAccessExpression(access) &&
+                        access.expression === node &&
+                        ts.isIdentifier(access.name) &&
+                        behaviours.has(access.name.text) &&
+                        // A write replaces the member on the instance, which the compiled
+                        // layout has no slot for.
+                        !(ts.isBinaryExpression(access.parent) && access.parent.left === access);
+                return;
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(body);
+        return sound;
+    };
+    for (const owner of chain) {
+        for (const member of owner.members) {
+            if (isStatic(member) || !(ts.isMethodDeclaration(member) || ts.isAccessor(member)))
+                continue;
+            const name = memberNameOf(member);
+            if (name !== null && overridden.has(name))
+                continue;
+            if (member.body && !readsOnlyBehaviour(member.body))
+                return false;
+        }
+    }
+    return true;
+};
+/**
+ * Whether the module statements between `C`'s declaration and its
+ * re-parenting can run nothing that reaches a `C` instance -- the compiled
+ * dispatch holds `B` as the parent from the start, so a lookup before the call
+ * would already see `B`'s members.
+ *
+ * Declarations run nothing. An expression statement may call only the
+ * standard `Object`'s reflection functions, `Symbol.for`, or `forEach` on an array literal
+ * with those calls inside, which is how a module installs prototype members
+ * from a key list; a function stored in an object literal (a descriptor's
+ * `get` or `value`) is not run by storing it. Anything else -- a `new`, a call
+ * to the program's own functions -- is refused.
+ */
+const nothingRunsBetween = (checker, derived, statement) => {
+    const statements = derived.getSourceFile().statements;
+    const from = statements.indexOf(derived);
+    const to = statements.indexOf(statement);
+    if (from < 0 || to <= from)
+        return false;
+    let quiet = true;
+    const visit = (node) => {
+        if (!quiet)
+            return;
+        if (ts.isFunctionLike(node) && ts.isObjectLiteralElementLike(node.parent))
+            return;
+        if (ts.isMethodDeclaration(node) && ts.isObjectLiteralExpression(node.parent))
+            return;
+        if (ts.isNewExpression(node) || ts.isTaggedTemplateExpression(node) || ts.isDecorator(node)) {
+            quiet = false;
+            return;
+        }
+        if (ts.isCallExpression(node)) {
+            const callee = node.expression;
+            const receiver = ts.isPropertyAccessExpression(callee) ? callee.expression : null;
+            const standard = (name) => receiver !== null &&
+                ts.isIdentifier(receiver) &&
+                isStandardInterfaceType(checker, receiver, name, checker.getTypeAtLocation(receiver));
+            // `Symbol.for` only reads the global symbol registry, which is how a
+            // module names a well-known inspection hook it installs.
+            const reflective = ts.isPropertyAccessExpression(callee) &&
+                (standard('ObjectConstructor') ||
+                    (callee.name.text === 'for' && standard('SymbolConstructor')) ||
+                    (callee.name.text === 'forEach' && ts.isArrayLiteralExpression(callee.expression) && node.arguments.every(ts.isArrowFunction)));
+            if (!reflective) {
+                quiet = false;
+                return;
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    for (const between of statements.slice(from + 1, to)) {
+        if (ts.isVariableStatement(between)) {
+            for (const declaration of between.declarationList.declarations)
+                if (declaration.initializer)
+                    visit(declaration.initializer);
+        }
+        else if (ts.isExpressionStatement(between) || ts.isEmptyStatement(between))
+            visit(between);
+        else if (!ts.isFunctionDeclaration(between) &&
+            !ts.isInterfaceDeclaration(between) &&
+            !ts.isTypeAliasDeclaration(between) &&
+            !ts.isImportDeclaration(between))
+            return false;
+        if (!quiet)
+            return false;
+    }
+    return true;
+};
+/**
+ * `Object.setPrototypeOf(C.prototype, B.prototype)` run once, at the top level
+ * of the module that declares the class `C`, where `C` has no `extends` and
+ * `B` is a class this program compiles.
+ *
+ * `@hono/node-server`'s `RequestHeaders` is the shape: it answers the
+ * `Headers` surface itself and re-parents its prototype so its instances are
+ * `instanceof Headers`. After the call `C.prototype`'s [[Prototype]] is
+ * `B.prototype`, so for member lookup a `C` instance is exactly what an
+ * instance of `class C extends B` would be, except that `B`'s constructor
+ * never ran on it. That is what this compiler models: `B` becomes `C`'s base
+ * for layout, dispatch and upcasts, and the call itself checks at run time
+ * that the value really is `B` and links the two class evaluations
+ * (`gea::reparentNativeClass`). `reparentingIsSound` is what makes the
+ * missing constructor run unobservable.
+ *
+ * The class and the call must be statements of the same module body with the
+ * call unconditional, so the re-parenting happens before any function the
+ * module exports can run. A class with `extends` already has a prototype
+ * parent that its constructor's `super()` initializes, which this does not
+ * model.
+ *
+ * `Object` is authenticated by the caller, each with its own authority.
+ */
+export const prototypeReparentingOf = (checker, call) => {
+    const statement = call.parent;
+    if (!ts.isExpressionStatement(statement) || !ts.isSourceFile(statement.parent) || call.arguments.length !== 2)
+        return null;
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== 'setPrototypeOf')
+        return null;
+    const [target, parent] = call.arguments;
+    const derivedName = prototypeOwnerOf(target);
+    const baseValue = prototypeOwnerOf(parent);
+    if (!derivedName || !baseValue || !ts.isIdentifier(derivedName))
+        return null;
+    if (!ts.isIdentifier(baseValue) && !ts.isPropertyAccessExpression(baseValue))
+        return null;
+    const symbol = checker.getSymbolAtLocation(derivedName);
+    const declarations = symbol?.declarations ?? [];
+    const derived = declarations.length === 1 ? declarations[0] : undefined;
+    if (!derived || !ts.isClassDeclaration(derived) || derived.parent !== statement.parent)
+        return null;
+    if (derived.heritageClauses?.some((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword))
+        return null;
+    if (derived.typeParameters?.length)
+        return null;
+    const base = classOfConstructorValue(checker, baseValue);
+    if (!base || base === derived || base.typeParameters?.length)
+        return null;
+    const chain = programClassChainOf(checker, base);
+    if (!chain || chain.includes(derived) || !reparentingIsSound(derived, chain))
+        return null;
+    if (!nothingRunsBetween(checker, derived, statement))
+        return null;
+    return { derived, baseValue, base };
+};
+/** Whether `call` is `Object.setPrototypeOf` on the standard `Object`. */
+export const isObjectSetPrototypeOf = (checker, call) => {
+    const callee = call.expression;
+    if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== 'setPrototypeOf')
+        return false;
+    return isGlobalObjectConstructor(checker, callee.expression, checker.getTypeAtLocation(callee.expression));
+};
+/**
+ * Every class this program re-parents. A class re-parented twice has no single
+ * base and is left out, so both of its calls stay with the mutation census.
+ */
+export const prototypeReparentingsOf = (checker, identities, files) => {
+    const byClass = new Map();
+    const calls = new Map();
+    const constructorCalls = [];
+    for (const file of files) {
+        if (file.isDeclarationFile)
+            continue;
+        for (const statement of file.statements) {
+            if (!ts.isExpressionStatement(statement) || !ts.isCallExpression(statement.expression))
+                continue;
+            const call = statement.expression;
+            if (!isObjectSetPrototypeOf(checker, call))
+                continue;
+            const reparenting = prototypeReparentingOf(checker, call);
+            if (!reparenting) {
+                constructorCalls.push(call);
+                continue;
+            }
+            byClass.set(reparenting.derived, byClass.has(reparenting.derived) ? null : reparenting);
+            calls.set(call, reparenting);
+        }
+    }
+    // `Object.setPrototypeOf(C, B)` beside `Object.setPrototypeOf(C.prototype,
+    // B.prototype)` is the other half of the same `class C extends B`: the
+    // constructor's own [[Prototype]], through which `C` inherits `B`'s static
+    // members. The model already gives `C` that base for both halves, so the
+    // call is the same event -- it checks the value is `B` and links the two
+    // class evaluations, which a second link to the same parent leaves as it is.
+    // Alone, it is not modelled: `C.prototype` would still inherit from
+    // `Object.prototype`.
+    for (const call of constructorCalls) {
+        const [target, parent] = call.arguments;
+        if (call.arguments.length !== 2 || !ts.isIdentifier(target))
+            continue;
+        const derived = checker.getSymbolAtLocation(target)?.declarations?.find(ts.isClassDeclaration);
+        const reparenting = derived ? byClass.get(derived) : undefined;
+        if (!reparenting || parent.getText() !== reparenting.baseValue.getText())
+            continue;
+        if (classOfConstructorValue(checker, parent) !== reparenting.base)
+            continue;
+        calls.set(call, reparenting);
+    }
+    const bases = new Map();
+    for (const [derived, reparenting] of byClass)
+        if (reparenting)
+            bases.set(identities.declarationIdOf(derived), identities.declarationIdOf(reparenting.base));
+    return {
+        of: (call) => {
+            const reparenting = calls.get(call);
+            return reparenting && byClass.get(reparenting.derived) === reparenting ? reparenting : null;
+        },
+        baseOf: (derived) => byClass.get(derived)?.base ?? null,
+        bases
+    };
+};

package/dist/semantics/stable-checker.d.ts

@@ -0,0 +1,10 @@
+import type ts from 'typescript';
+/**
+ * The program and checker are immutable inputs to census inference. TypeScript
+ * nevertheless allocates fresh object-literal types on repeated public
+ * getTypeAtLocation calls (its internal expression cache is flow-dependent).
+ * Memoize that query at the program boundary so every census shares its exact
+ * answer, including nested property identities. Improved census facts remain
+ * separate: a new receiver or a different narrowed read site is not this query.
+ */
+export declare const withStableTypeQueries: (checker: ts.TypeChecker) => ts.TypeChecker;

package/dist/semantics/stable-checker.js

@@ -0,0 +1,148 @@
+/**
+ * The program and checker are immutable inputs to census inference. TypeScript
+ * nevertheless allocates fresh object-literal types on repeated public
+ * getTypeAtLocation calls (its internal expression cache is flow-dependent).
+ * Memoize that query at the program boundary so every census shares its exact
+ * answer, including nested property identities. Improved census facts remain
+ * separate: a new receiver or a different narrowed read site is not this query.
+ */
+export const withStableTypeQueries = (checker) => {
+    const types = new WeakMap();
+    const getTypeAtLocation = (node) => {
+        const cached = types.get(node);
+        if (cached)
+            return cached;
+        const type = checker.getTypeAtLocation(node);
+        types.set(node, type);
+        return type;
+    };
+    // `getSymbolAtLocation` is memoized for a different reason than the query
+    // above, and a stronger one. It is not flow-dependent -- it resolves the name
+    // standing at a syntactic position, which a fixed program answers the same
+    // way every time -- so caching it cannot hide a narrowing the way an
+    // unmemoized type query could. It is simply the most expensive question this
+    // compiler asks TypeScript, and several censuses ask it of the same node.
+    //
+    // MISSES are cached too, and they are the ones that matter: an identifier
+    // that resolves to nothing sends the checker down its diagnostic path
+    // (`getCannotFindNameDiagnosticForName`, and for JSDoc the link-parsing
+    // beside it), which is far more work than a hit. A three.js-scale program is
+    // full of them. `undefined` cannot be told from absent in a WeakMap, so the
+    // misses are remembered in a set of their own.
+    const symbols = new WeakMap();
+    const symbolMisses = new WeakSet();
+    const getSymbolAtLocation = (node) => {
+        const cached = symbols.get(node);
+        if (cached)
+            return cached;
+        if (symbolMisses.has(node))
+            return undefined;
+        const symbol = checker.getSymbolAtLocation(node);
+        if (symbol)
+            symbols.set(node, symbol);
+        else
+            symbolMisses.add(node);
+        return symbol;
+    };
+    // The six queries below are memoized on a STRICTLY STRONGER argument than
+    // either of the two above: they are functions of a type's identity and
+    // nothing else. No node, no flow position, no narrowing site takes part, so
+    // there is no narrowed reading for a cache to freeze -- narrowing is decided
+    // at `getTypeAtLocation`, which is memoized separately and per node. Whatever
+    // type reaches here has already been chosen; these answer fixed structural
+    // questions about it, and a fixed program answers them the same way forever.
+    //
+    // They are memoized because the escape proof asks them in the innermost loop
+    // of a coinductive walk that revisits the same family on every member of
+    // every class, and because each is expensive in its own right: apparent-type
+    // and property resolution force lazy member tables, and `getPropertiesOfType`
+    // materializes the whole inherited member list of a three.js class on every
+    // call.
+    //
+    // The array-returning three hand back the checker's own array, shared by
+    // every caller of the same type -- sound only while no consumer mutates a
+    // result. None does today (every call site spreads, iterates, `find`s or
+    // `flatMap`s), and a consumer that wants to sort or push must copy first.
+    const apparentTypes = new WeakMap();
+    const getApparentType = (type) => {
+        const cached = apparentTypes.get(type);
+        if (cached)
+            return cached;
+        const apparent = checker.getApparentType(type);
+        apparentTypes.set(type, apparent);
+        return apparent;
+    };
+    const nonNullableTypes = new WeakMap();
+    const getNonNullableType = (type) => {
+        const cached = nonNullableTypes.get(type);
+        if (cached)
+            return cached;
+        const bare = checker.getNonNullableType(type);
+        nonNullableTypes.set(type, bare);
+        return bare;
+    };
+    const propertyLists = new WeakMap();
+    const getPropertiesOfType = (type) => {
+        const cached = propertyLists.get(type);
+        if (cached)
+            return cached;
+        const properties = checker.getPropertiesOfType(type);
+        propertyLists.set(type, properties);
+        return properties;
+    };
+    const baseTypeLists = new WeakMap();
+    const getBaseTypes = (type) => {
+        const cached = baseTypeLists.get(type);
+        if (cached)
+            return cached;
+        const bases = checker.getBaseTypes(type);
+        baseTypeLists.set(type, bases);
+        return bases;
+    };
+    // A miss is as worth remembering as a hit here: an absent property sends the
+    // checker through the full apparent-type/index-signature resolution before it
+    // can say no, and the escape proof asks for names most types do not have. A
+    // `Map` per type keeps absence distinguishable from "not asked yet".
+    const propertiesByName = new WeakMap();
+    const getPropertyOfType = (type, name) => {
+        let byName = propertiesByName.get(type);
+        if (!byName)
+            propertiesByName.set(type, (byName = new Map()));
+        if (byName.has(name))
+            return byName.get(name);
+        const property = checker.getPropertyOfType(type, name);
+        byName.set(name, property);
+        return property;
+    };
+    const signaturesByKind = new WeakMap();
+    const getSignaturesOfType = (type, kind) => {
+        let byKind = signaturesByKind.get(type);
+        if (!byKind)
+            signaturesByKind.set(type, (byKind = new Map()));
+        const cached = byKind.get(kind);
+        if (cached)
+            return cached;
+        const signatures = checker.getSignaturesOfType(type, kind);
+        byKind.set(kind, signatures);
+        return signatures;
+    };
+    // Preserve the checker's full surface, including capability-checked internal
+    // constructors used by existing inference producers, without copying it.
+    const stable = {
+        getTypeAtLocation,
+        getSymbolAtLocation,
+        getApparentType,
+        getNonNullableType,
+        getPropertiesOfType,
+        getBaseTypes,
+        getPropertyOfType,
+        getSignaturesOfType
+    };
+    return new Proxy(checker, {
+        get: (target, key, receiver) => {
+            if (typeof key === 'string' && key in stable)
+                return stable[key];
+            return Reflect.get(target, key, receiver);
+        }
+    });
+};

package/dist/semantics/subclass-member-overlay-transform.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How a declarer's text is read: as the checker will see it, not as it sits
+ * on disk.
+ *
+ * The index below scans every file of the package to learn what each subclass
+ * assigns and with what stated type. It used to read those files with
+ * `readFileSync`, while the program itself reads them through the transform
+ * chain -- and a plugin's `transformSource` runs in that chain AFTER this
+ * overlay. So a type a package's plugin states for a subclass field (three's
+ * `ShaderMaterial.defaultAttributeValues`, restated from `@type {Object}` to
+ * a `Record<string, number[]|undefined>`) reached the checker for that
+ * subclass and never reached this index, which still read `{Object}` off the
+ * disk and refused the declarer. The base-typed read then stayed `any`: a
+ * box, and an exact-payload unbox at the reader, for a value both ends had
+ * already typed.
+ *
+ * Two readers of one declarer text are two authorities; this makes the index
+ * read what the checker reads. Only the PLUGIN transforms are applied here
+ * (`compiler.ts` hands them in): the generic transforms ahead of this one in
+ * the chain rewrite shapes this scan already recognises raw (`Object.
+ * defineProperty(this, ...)`, JSDoc namepaths), and a scan of their output
+ * would be a second copy of their rules. A file a plugin refuses -- an anchor
+ * it never compiled against -- reads as it sits on disk: the plugin states
+ * nothing about it.
+ */
+export type DeclarerReader = (filePath: string) => string;
+/**
+ * The overlay, reading declarers through `read` -- see `DeclarerReader`.
+ * `compiler.ts` builds one per compilation with that compilation's plugin
+ * transforms; a caller with no plugins may pass `readFileSync` itself.
+ */
+export declare const createSubclassMemberOverlayTransform: (read: DeclarerReader) => (input: {
+    readonly fileName: string;
+    readonly text: string;
+}) => string | null;