@geastack/compiler 1.0.15

package/dist/semantics/normalize/return-paths.d.ts

@@ -0,0 +1,2 @@
+import ts from 'typescript';
+export declare const definitelyReturns: (statements: readonly ts.Statement[]) => boolean;

package/dist/semantics/normalize/return-paths.js

@@ -0,0 +1,28 @@
+import ts from 'typescript';
+/**
+ * Whether control can fall off the end of these statements without hitting a
+ * `return`/`throw`.
+ *
+ * Deliberately conservative: only a `return`, a `throw`, a `Block` whose own
+ * statements definitely exit, and an `if`/`else` where BOTH arms definitely
+ * exit are recognised as definitely exiting. A `for`/`while`/`switch`/`try`
+ * that might definitely exit is answered `false` -- not because it cannot,
+ * but because proving it needs real control-flow analysis this module does
+ * not build, and under-approximating here only ever REFUSES a function this
+ * compiler could have resolved, never accepts one it should not have. See
+ * `isUnusableEvidence`'s sibling reasoning: refusing is always the safe
+ * default in this module.
+ */
+const definitelyExits = (node) => {
+    if (ts.isReturnStatement(node) || ts.isThrowStatement(node))
+        return true;
+    if (ts.isBlock(node))
+        return definitelyReturns(node.statements);
+    if (ts.isIfStatement(node))
+        return node.elseStatement !== undefined && definitelyExits(node.thenStatement) && definitelyExits(node.elseStatement);
+    return false;
+};
+export const definitelyReturns = (statements) => {
+    const last = statements[statements.length - 1];
+    return last !== undefined && definitelyExits(last);
+};

package/dist/semantics/normalize/script-global-redefinition.d.ts

@@ -0,0 +1,44 @@
+import ts from 'typescript';
+import type { UnresolvableNameCensus } from './unresolvable-names.js';
+/**
+ * Whether `declaration` is a `var` or function declaration at the top level
+ * of a SCRIPT: the declarations ECMA-262 9.1.1.4.17/18 (CreateGlobalVarBinding,
+ * CreateGlobalFunctionBinding) install as own data properties of the global
+ * object. A `let`/`const`/`class` at the same level lives in the global
+ * declarative record and is NOT a property of the object; a module's
+ * top-level declarations are the module's own; an ambient declaration
+ * (`declare var`, in a `.d.ts` or not) creates no binding at all -- it is a
+ * host's claim, which `hostGlobalMemberDeclarationOf` judges by its own rule.
+ */
+export declare const isScriptGlobalObjectPropertyDeclaration: (declaration: ts.Declaration) => boolean;
+export interface ScriptGlobalRedefinition {
+    /** The script-level `var` whose global-object property is redefined. */
+    readonly declaration: ts.VariableDeclaration;
+    readonly symbol: ts.Symbol;
+    /** The descriptor's `value`, which becomes the var's value. */
+    readonly value: ts.Expression;
+}
+/**
+ * `Object.defineProperty(globalThis, 'K', { value: V })` where `K` is the
+ * program's own script-level `var`, read as the plain store `K = V` it is.
+ *
+ * `@hono/node-server` swaps the platform's `Request` and `Response` this way.
+ * A script `var` is an own data property of the global object that is
+ * writable, enumerable and NOT configurable (9.1.1.4.17). For a descriptor
+ * naming only `value`, ValidateAndApplyPropertyDescriptor (10.1.6.3) keeps
+ * every attribute and replaces the value, and a writable property admits
+ * that. So the call writes the var's cell and nothing else, and the call
+ * returns the global object, which is why only a call whose result is
+ * discarded is claimed.
+ *
+ * Any other descriptor is not this store: `writable: false` changes an
+ * attribute, `configurable: true`, `enumerable: false` or an accessor throws
+ * against the non-configurable property, and a spread or computed member
+ * states keys nobody can read here. Those stay with the mutation census.
+ *
+ * The caller authenticates `Object.defineProperty` itself, each with its own
+ * authority. The census and the invocation producer both ask this, so the
+ * write the producer lowers is exactly the write the census stops tainting
+ * the var for.
+ */
+export declare const scriptGlobalValueRedefinitionOf: (checker: ts.TypeChecker, names: Pick<UnresolvableNameCensus, "isIntrinsicGlobalThis">, call: ts.CallExpression) => ScriptGlobalRedefinition | null;

package/dist/semantics/normalize/script-global-redefinition.js

@@ -0,0 +1,75 @@
+import ts from 'typescript';
+import { unwrapErasedExpression } from './producers/erasure.js';
+/**
+ * Whether `declaration` is a `var` or function declaration at the top level
+ * of a SCRIPT: the declarations ECMA-262 9.1.1.4.17/18 (CreateGlobalVarBinding,
+ * CreateGlobalFunctionBinding) install as own data properties of the global
+ * object. A `let`/`const`/`class` at the same level lives in the global
+ * declarative record and is NOT a property of the object; a module's
+ * top-level declarations are the module's own; an ambient declaration
+ * (`declare var`, in a `.d.ts` or not) creates no binding at all -- it is a
+ * host's claim, which `hostGlobalMemberDeclarationOf` judges by its own rule.
+ */
+export const isScriptGlobalObjectPropertyDeclaration = (declaration) => {
+    const file = declaration.getSourceFile();
+    if (file.isDeclarationFile || ts.isExternalModule(file))
+        return false;
+    if ((ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Ambient) !== 0)
+        return false;
+    if (ts.isFunctionDeclaration(declaration))
+        return declaration.parent === file;
+    if (!ts.isVariableDeclaration(declaration))
+        return false;
+    const list = declaration.parent;
+    if (!ts.isVariableDeclarationList(list) || (list.flags & ts.NodeFlags.BlockScoped) !== 0)
+        return false;
+    return ts.isVariableStatement(list.parent) && list.parent.parent === file;
+};
+/**
+ * `Object.defineProperty(globalThis, 'K', { value: V })` where `K` is the
+ * program's own script-level `var`, read as the plain store `K = V` it is.
+ *
+ * `@hono/node-server` swaps the platform's `Request` and `Response` this way.
+ * A script `var` is an own data property of the global object that is
+ * writable, enumerable and NOT configurable (9.1.1.4.17). For a descriptor
+ * naming only `value`, ValidateAndApplyPropertyDescriptor (10.1.6.3) keeps
+ * every attribute and replaces the value, and a writable property admits
+ * that. So the call writes the var's cell and nothing else, and the call
+ * returns the global object, which is why only a call whose result is
+ * discarded is claimed.
+ *
+ * Any other descriptor is not this store: `writable: false` changes an
+ * attribute, `configurable: true`, `enumerable: false` or an accessor throws
+ * against the non-configurable property, and a spread or computed member
+ * states keys nobody can read here. Those stay with the mutation census.
+ *
+ * The caller authenticates `Object.defineProperty` itself, each with its own
+ * authority. The census and the invocation producer both ask this, so the
+ * write the producer lowers is exactly the write the census stops tainting
+ * the var for.
+ */
+export const scriptGlobalValueRedefinitionOf = (checker, names, call) => {
+    if (!ts.isExpressionStatement(call.parent) || call.arguments.length !== 3)
+        return null;
+    const [target, key, descriptor] = call.arguments;
+    const holder = unwrapErasedExpression(target);
+    if (!ts.isIdentifier(holder) || !names.isIntrinsicGlobalThis(holder))
+        return null;
+    if (!ts.isStringLiteralLike(key) || !ts.isObjectLiteralExpression(descriptor) || descriptor.properties.length !== 1)
+        return null;
+    const [property] = descriptor.properties;
+    if (!property || !ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name) || property.name.text !== 'value')
+        return null;
+    const symbol = checker.getPropertyOfType(checker.getTypeAtLocation(holder), key.text);
+    const declaration = symbol?.valueDeclaration;
+    if (!symbol || !declaration || !ts.isVariableDeclaration(declaration) || !isScriptGlobalObjectPropertyDeclaration(declaration))
+        return null;
+    // A second VALUE declaration of the same name (another script's `var`, or a
+    // host's) would make the property's one cell ambiguous. A merged `interface`
+    // of the same name (`interface Request` beside `var Request`) declares no
+    // value and does not.
+    const values = (symbol.declarations ?? []).filter((candidate) => ts.isVariableDeclaration(candidate) || ts.isFunctionDeclaration(candidate) || ts.isClassLike(candidate));
+    if (values.length !== 1)
+        return null;
+    return { declaration, symbol, value: property.initializer };
+};

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

@@ -0,0 +1,201 @@
+import ts from 'typescript';
+import type { ProgramReachability } from './reachability.js';
+import type { NamespacePathCensus } from './namespace-paths.js';
+/**
+ * Monomorphization: one copy of a generic body per distinct instantiation.
+ *
+ * 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 wrong is compiling the body *once* with the
+ * hole still open, because the language says a generic body exists once per
+ * instantiation and each of those has different types in it.
+ *
+ * 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" hands a caller a struct of the wrong size and shape. Erasure is not
+ * a weaker monomorphization here, it is a different and unsound thing.
+ *
+ * This module answers only the enumeration question -- which instantiations the
+ * program makes -- and answers it before anything is normalized, because the
+ * census has to know how many copies of each body to emit before it emits any.
+ * Substituting the bindings is the structural layer's job, and minting the
+ * copies is the census's.
+ *
+ * A specialization is identified by an ORDINAL, not by the spelling of its type
+ * arguments. `Store<AppState>` is `s0` because it is the first instantiation of
+ * `Store` the deterministic walk reaches, exactly as a node is identified by its
+ * position in that same walk. A key built from the argument's name would put a
+ * declaration's spelling into an identity, which is the one thing identities
+ * here may never carry.
+ */
+/** One instantiation of one generic declaration: what each of its type parameters is filled with. */
+export interface Specialization {
+    /** Position among this declaration's instantiations, in deterministic walk order. */
+    readonly ordinal: number;
+    /** The type filling each of the declaration's type parameters, in declaration order. */
+    readonly arguments: readonly ts.Type[];
+    /**
+     * This instantiation as the CHECKER spells it -- `Collection<Document>`, not
+     * `Collection` plus a filling to apply.
+     *
+     * The public checker API cannot instantiate a type (this module's
+     * `induceFromHeritage` records the same gap), so the only instantiated
+     * spelling available is one the program itself wrote and the checker already
+     * resolved. A copy minted from a type reference has exactly that; one induced
+     * through a heritage clause or inferred from a call's arguments does not, and
+     * answers `null`.
+     *
+     * It is what makes a MEMBER of a generic answerable. Substituting a parameter
+     * only ever rewrites a bare `T`, so a member type that merely mentions one --
+     * `filter: Filter<TSchema>`, `Awaited<WithId<TSchema>>` -- keeps the hole and
+     * every deferred conditional inside it stays deferred. Read the member off
+     * this type instead (`getPropertyOfType`, then the member's own signature)
+     * and the checker hands back the instantiated type with those conditionals
+     * already evaluated, because evaluating them is what instantiating meant.
+     */
+    readonly instantiated: ts.Type | null;
+    /**
+     * The uninstantiated signature this copy came from paired with the one the
+     * checker resolved the call to, for a copy minted from a CALL rather than
+     * from a type reference.
+     *
+     * The same fact as `instantiated`, for the other half of the generics. A
+     * call site has no instantiated TYPE to read members off -- the callee is a
+     * function, not a parent -- but it does have the very thing `instantiated`
+     * exists to supply: an image of the open shape with every parameter filled,
+     * which `getResolvedSignature` already computed to type-check the call.
+     * Pairing the two gives a generic FUNCTION's parameter and return types the
+     * same answer a generic CLASS's members get.
+     */
+    readonly instantiatedSignature: readonly [ts.Signature, ts.Signature] | null;
+    /** The filling for one type-parameter declaration, or `null` when this specialization does not bind it. */
+    readonly bindingOf: (parameter: ts.Declaration) => ts.Type | null;
+    /**
+     * What this copy's own instantiation filled an OPEN composite type with:
+     * `T[]` -> `string[]`, `Mutable<T>` -> `Mutable<VariableDeclaration>`. Read
+     * from the checker's resolved signature of the call that minted the copy,
+     * paired against the generic one, so every type the copy's frame writes
+     * with a hole inside has the checker's own closed spelling beside it. A
+     * bare parameter is `bindingOf`'s question; this answers the shapes built
+     * around one, which the public checker API cannot instantiate on request.
+     * `null` for a copy minted by substitution or heritage, which had no call.
+     */
+    readonly fillingOf: (open: ts.Type) => ts.Type | null;
+}
+export interface SpecializationCensus {
+    /**
+     * Every instantiation of this generic declaration, or an empty list when the
+     * program instantiates it none -- a generic nothing uses has no body worth
+     * copying, and emitting an uninstantiated copy would put the open hole back.
+     */
+    readonly specializationsOf: (declaration: ts.Declaration) => readonly Specialization[];
+    /** Whether this declaration is one the census specializes at all. */
+    readonly isGeneric: (declaration: ts.Declaration) => boolean;
+    /**
+     * The instantiation a particular site makes, so a call or a heritage clause
+     * can name the copy it reaches rather than the generic it was written against.
+     *
+     * `substitute` is what the *asking* copy binds a type parameter to, and it is
+     * what makes this answer honest for a site written inside another generic.
+     * `class ReactiveComponent<Root> extends Component<Root> {}` names one copy of
+     * `Component` per copy of `ReactiveComponent`, so the ordinal is a property of
+     * the site *and* of the copy asking -- never of the node alone. Storing one
+     * ordinal on the node would answer every copy with whichever was seen first,
+     * which is the same shape of defect `copyKeyOf` exists to prevent one level
+     * up. Asking with no substitution is the root scope's own question; a site
+     * whose fillings are still holes after substitution answers `null`, because an
+     * open hole names no copy.
+     */
+    readonly specializationAt: (node: ts.Node, substitute?: (type: ts.Type) => ts.Type) => {
+        readonly declaration: ts.Declaration;
+        readonly ordinal: number;
+    } | null;
+    /**
+     * The copies a call through a CHOICE of generic functions reaches -- one
+     * per member of the set the callee's type is (`genericFunctionSetMembersOf`,
+     * model/structural-types.ts) -- in the same substitution discipline as
+     * `specializationAt`. `null` when the call is not through such a set or any
+     * member's copy is still open in the asking copy.
+     */
+    readonly setSpecializationsAt: (node: ts.Node, substitute?: (type: ts.Type) => ts.Type) => readonly {
+        readonly declaration: ts.Declaration;
+        readonly ordinal: number;
+    }[] | null;
+    /**
+     * The copy an INSTANTIATED class or interface type names -- `Box<number>`
+     * read off a receiver expression -- in the same substitution discipline as
+     * `specializationAt`: the type's own arguments, substituted by the asking
+     * copy, looked up among the tuples this census minted. `null` for a type
+     * that is not an instantiation of a censused generic, or whose arguments
+     * are still holes after substitution.
+     *
+     * What lets a use site OUTSIDE a class reach the copy its receiver is an
+     * instance of: `numbers.pick('a')` with `numbers: Box<number>` runs
+     * `pick`'s frame in `Box<number>`'s copy, not the root's.
+     */
+    readonly specializationOfInstance: (type: ts.Type, substitute?: (type: ts.Type) => ts.Type) => {
+        readonly declaration: ts.Declaration;
+        readonly ordinal: number;
+    } | null;
+    /**
+     * Whether a class's copies can be more than one physical layout: two copies
+     * whose layout-RELEVANT fillings (`layoutRelevantParameterIndices`) are
+     * different checker types.
+     *
+     * Copies are deduped by the identity of their fillings (the checker interns
+     * types), so this is answered without translating a single type -- which
+     * is the point: structural ids are spelled into struct names, and a class
+     * every one of whose copies agrees on its relevant fillings (hono's
+     * `Hono<E,S,BasePath>` across every route registration) must be typed
+     * exactly as it was before any class had two layouts. Two different
+     * objects can still be one physical layout (`Carrier<'a' | 'b'>` beside
+     * `Carrier<string>`); the deriver's `physicalClassDeclarationOf` decides
+     * that on the fillings' representations, and this only says whether it has
+     * a question. `false` for an ambient class -- its instances belong to a
+     * host protocol keyed on the root -- and for a generic with one copy.
+     */
+    readonly copiesMayDifferInLayout: (declaration: ts.Declaration) => boolean;
+    /**
+     * For a class whose copies must NOT split (`copiesMayDifferInLayout` is
+     * false) but whose layout-relevant fillings still differ, the fillings the
+     * one shared struct is built from: the copy every other copy is assignable
+     * TO, which is the most specific one.
+     *
+     * Without this the collapse is dishonest. The instance side keys its anchor
+     * on the written fillings, so `ReadableStream<any>` and
+     * `ReadableStream<Uint8Array>` are two structural shapes -- and they then
+     * map to ONE physical class, whose field carriers come from whichever
+     * anchor happened to complete first. When that is the `any` copy the struct
+     * stores `dynamic` and every read in the concrete copy refuses, because
+     * `dynamic -> typed-array(uint8)` is a narrowing no target installs. Naming
+     * the most specific copy instead makes every other copy's read a WIDENING,
+     * which is licensed, and gives the collapse one anchor rather than two
+     * sharing a struct by accident of ordering.
+     *
+     * `null` when the class may split, when its copies already agree, or when
+     * no copy is assignable to all the others -- there is no honest single
+     * layout then, and the caller keeps what it wrote.
+     */
+    readonly canonicalLayoutFillings: (declaration: ts.Declaration) => readonly ts.Type[] | null;
+}
+export declare const emptySpecializationCensus: SpecializationCensus;
+/**
+ * The declaration whose type parameters a node's value actually writes down.
+ *
+ * `function identity<T>(x: T): T {}` and `const identity = <T>(x: T): T => x`
+ * are the same declaration written two ways -- both name a generic function,
+ * both are instantiated per call site -- and this census keys specializations
+ * on the node that CARRIES the type parameters, which for the second spelling
+ * is the arrow function rather than the variable declaration naming it.
+ *
+ * Every consumer that asks "which copy does this declaration belong to" has to
+ * ask about the same node, or the two halves disagree: `census.ts` forks the
+ * walk here, and `identities.ts`'s `useSitePath` resolves a name to a copy
+ * here. When only one of them hopped, the arrow forked per copy while the
+ * declaration holding it stayed at the root path -- and the binding recorded
+ * there cited an allocation that exists only inside a copy.
+ */
+export declare const genericSubjectOf: (node: ts.Declaration, targetOfName?: (name: ts.Identifier) => ts.Declaration | null) => ts.Declaration;
+export declare const censusSpecializations: (checker: ts.TypeChecker, sourceFiles: readonly ts.SourceFile[], reachable: ProgramReachability, namespacePaths: NamespacePathCensus) => SpecializationCensus;