@geastack/compiler 1.0.15

package/dist/semantics/normalize/unreduced-type-form.d.ts

@@ -0,0 +1,41 @@
+import ts from 'typescript';
+/**
+ * Whether a type is an UNREDUCED FORM: a conditional, an indexed access, a
+ * `keyof`, or a substitution the checker deferred and that no substitution
+ * this compiler performs will ever finish.
+ *
+ * The same thing `isUnusableEvidence` says about `any`/`void`/`never`, said
+ * about the other way a type can fail to be one: an unreduced form names a
+ * type EXPRESSION, not a type, and no carrier can be derived from an
+ * expression. `structural.ts` refuses exactly these at the end of the line --
+ * "an anonymous conditional type is still gated on a type parameter" -- and
+ * this is that same refusal, moved to where the form is first taken for
+ * evidence.
+ *
+ * It lives in its own module because THREE censuses independently answer "what
+ * is the type of this call" by reading a signature's declared return
+ * (`parameter-bindings.ts`, `return-bindings.ts`, `local-bindings.ts`), and a
+ * generic signature's declared return is exactly such a form. `Reflect.get`'s
+ * is `P extends keyof T ? T[P] : any`; nothing on any of those walks binds `T`
+ * or `P`, while the checker had already reduced the call itself to `any` (for
+ * a key `RegExp` does not declare) or `string` (for `flags`). Publishing the
+ * unreduced form is what refused `pattern-native-property-routing.ts` outright.
+ * One rule, asked by the census that publishes and by the resolver that
+ * consumes -- not a spelling per caller.
+ *
+ * A BARE TYPE PARAMETER is deliberately NOT one of these, which is what
+ * separates this from `open-type-form.ts`'s `isOpenTypeForm` (a different
+ * question: whether a RECEIVER is still polymorphic). Inside a monomorphized
+ * copy `T` is evidence -- the copy's own mapper substitutes it -- and refusing
+ * it took `assign<T extends object>(t, ...args)`'s `hasProperty(arg, p)`
+ * argument away from the census, which then bound `map: object` to the vacuous
+ * empty record while the copy's ABI declared the instantiated `Opts`. Measured
+ * as a lowering refusal on `assign-for-in-generic.ts`. Substitution finishes a
+ * type parameter; it does not finish a conditional.
+ *
+ * Refusing, never reducing: reducing is what the checker already did at the
+ * call site, and its answer is what these resolvers fall back to the moment a
+ * census declines. Doing it a second time here would be a second authority on
+ * one reduction.
+ */
+export declare const isUnreducedTypeForm: (type: ts.Type, seen?: Set<ts.Type>) => boolean;

package/dist/semantics/normalize/unreduced-type-form.js

@@ -0,0 +1,53 @@
+import ts from 'typescript';
+/**
+ * Whether a type is an UNREDUCED FORM: a conditional, an indexed access, a
+ * `keyof`, or a substitution the checker deferred and that no substitution
+ * this compiler performs will ever finish.
+ *
+ * The same thing `isUnusableEvidence` says about `any`/`void`/`never`, said
+ * about the other way a type can fail to be one: an unreduced form names a
+ * type EXPRESSION, not a type, and no carrier can be derived from an
+ * expression. `structural.ts` refuses exactly these at the end of the line --
+ * "an anonymous conditional type is still gated on a type parameter" -- and
+ * this is that same refusal, moved to where the form is first taken for
+ * evidence.
+ *
+ * It lives in its own module because THREE censuses independently answer "what
+ * is the type of this call" by reading a signature's declared return
+ * (`parameter-bindings.ts`, `return-bindings.ts`, `local-bindings.ts`), and a
+ * generic signature's declared return is exactly such a form. `Reflect.get`'s
+ * is `P extends keyof T ? T[P] : any`; nothing on any of those walks binds `T`
+ * or `P`, while the checker had already reduced the call itself to `any` (for
+ * a key `RegExp` does not declare) or `string` (for `flags`). Publishing the
+ * unreduced form is what refused `pattern-native-property-routing.ts` outright.
+ * One rule, asked by the census that publishes and by the resolver that
+ * consumes -- not a spelling per caller.
+ *
+ * A BARE TYPE PARAMETER is deliberately NOT one of these, which is what
+ * separates this from `open-type-form.ts`'s `isOpenTypeForm` (a different
+ * question: whether a RECEIVER is still polymorphic). Inside a monomorphized
+ * copy `T` is evidence -- the copy's own mapper substitutes it -- and refusing
+ * it took `assign<T extends object>(t, ...args)`'s `hasProperty(arg, p)`
+ * argument away from the census, which then bound `map: object` to the vacuous
+ * empty record while the copy's ABI declared the instantiated `Opts`. Measured
+ * as a lowering refusal on `assign-for-in-generic.ts`. Substitution finishes a
+ * type parameter; it does not finish a conditional.
+ *
+ * Refusing, never reducing: reducing is what the checker already did at the
+ * call site, and its answer is what these resolvers fall back to the moment a
+ * census declines. Doing it a second time here would be a second authority on
+ * one reduction.
+ */
+export const isUnreducedTypeForm = (type, seen = new Set()) => {
+    if (seen.has(type))
+        return false;
+    seen.add(type);
+    const deferred = ts.TypeFlags.Conditional | ts.TypeFlags.IndexedAccess | ts.TypeFlags.Index | ts.TypeFlags.Substitution;
+    if ((type.flags & deferred) !== 0)
+        return true;
+    if (type.isUnionOrIntersection())
+        return type.types.some((member) => isUnreducedTypeForm(member, seen));
+    const reference = type;
+    const args = (type.flags & ts.TypeFlags.Object) !== 0 ? (reference.typeArguments ?? []) : [];
+    return args.some((argument) => isUnreducedTypeForm(argument, seen));
+};

package/dist/semantics/normalize/unresolvable-names.d.ts

@@ -0,0 +1,56 @@
+import ts from 'typescript';
+/**
+ * Which value-position names resolve to no binding anywhere in the program.
+ *
+ * `typeof Float16Array !== 'undefined' && array instanceof Float16Array` --
+ * three's `WebGLAttributes.js:24`, and the same shape for `XRWebGLBinding`,
+ * `XRWebGLLayer` and `__THREE_DEVTOOLS__` -- names a global no declaration in
+ * this program introduces and no host declares. `getSymbolAtLocation` returns
+ * `undefined` for it, so there is no cell for `GetValue` to read and no
+ * `binding` operation any producer could mint, exactly as for the magic
+ * `arguments` binding.
+ *
+ * This is the same shape of fact as `arguments-objects.ts` and exists for the
+ * same reason: a question only the checker can answer, asked once here so a
+ * syntactic layer downstream can consult it without one.
+ * `producers/references.ts` PUBLISHES an unresolvable name's value and
+ * `citeExpressionResult` PREDICTS the result that publication carries -- and
+ * the two disagreeing is not an error anywhere, only a withheld citation that
+ * silently takes its consumers with it. That is precisely what happened: the
+ * producer published a Reference Record and no read, the predictor predicted a
+ * read, and every `typeof`/`instanceof` feature-detection guard in three.js
+ * was withheld along with the operations around it.
+ *
+ * ⛔ This census states only that a name has NO CELL. It says nothing about
+ * whether a branch guarded on that name is dead -- that is
+ * `dead-typeof-guards.ts`, whose warrant is a HOST'S STATEMENT about a global
+ * it declares absent, and which must not be widened to rest on an inference
+ * this compiler drew from a missing declaration.
+ */
+export interface UnresolvableNameCensus {
+    /** Whether a value-position name here resolves to no binding at all. */
+    readonly hasNoCell: (node: ts.Node) => boolean;
+    /** Whether this is TypeScript's declarationless intrinsic `globalThis` symbol. */
+    readonly isIntrinsicGlobalThis: (node: ts.Node) => boolean;
+    /** How many such names this census found, for measurement. */
+    readonly count: number;
+}
+/** A census that finds nothing, for callers that state no program. */
+export declare const emptyUnresolvableNameCensus: UnresolvableNameCensus;
+/**
+ * The symbol a name in value position resolves to.
+ *
+ * For a shorthand property (`{ durationMs }`) the name is doing two jobs at
+ * once -- it is the property key AND a reference to the local binding of the
+ * same name -- and `getSymbolAtLocation` answers with the property symbol,
+ * which has no value cell. `getShorthandAssignmentValueSymbol` is the
+ * checker's own answer to the second job, so asking it is a citation rather
+ * than a repair: the value symbol is the local `durationMs`, exactly as it
+ * would be had the source spelled `{ durationMs: durationMs }`.
+ *
+ * Owned here rather than in `producers/references.ts` (its only other reader)
+ * so that the producer and this census cannot answer "does this name resolve"
+ * two different ways. One rule, one place.
+ */
+export declare const valueSymbolAt: (checker: ts.TypeChecker, node: ts.Node) => ts.Symbol | undefined;
+export declare const censusUnresolvableNames: (checker: ts.TypeChecker, files: readonly ts.SourceFile[]) => UnresolvableNameCensus;

package/dist/semantics/normalize/unresolvable-names.js

@@ -0,0 +1,140 @@
+import ts from 'typescript';
+/** A census that finds nothing, for callers that state no program. */
+export const emptyUnresolvableNameCensus = {
+    hasNoCell: () => false,
+    isIntrinsicGlobalThis: () => false,
+    count: 0
+};
+/**
+ * The symbol a name in value position resolves to.
+ *
+ * For a shorthand property (`{ durationMs }`) the name is doing two jobs at
+ * once -- it is the property key AND a reference to the local binding of the
+ * same name -- and `getSymbolAtLocation` answers with the property symbol,
+ * which has no value cell. `getShorthandAssignmentValueSymbol` is the
+ * checker's own answer to the second job, so asking it is a citation rather
+ * than a repair: the value symbol is the local `durationMs`, exactly as it
+ * would be had the source spelled `{ durationMs: durationMs }`.
+ *
+ * Owned here rather than in `producers/references.ts` (its only other reader)
+ * so that the producer and this census cannot answer "does this name resolve"
+ * two different ways. One rule, one place.
+ */
+export const valueSymbolAt = (checker, node) => {
+    const parent = node.parent;
+    if (ts.isShorthandPropertyAssignment(parent) && parent.name === node) {
+        return checker.getShorthandAssignmentValueSymbol(parent) ?? checker.getSymbolAtLocation(node);
+    }
+    const symbol = checker.getSymbolAtLocation(node);
+    return symbol && ts.isIdentifier(node) ? (lexicalSymbolBehindExportSynthesis(checker, node, symbol) ?? symbol) : symbol;
+};
+/**
+ * Checked JavaScript: the checker binds the `module` of `module.exports = f`
+ * (and the `exports` of `exports.x = ...`) to the FILE's own synthetic
+ * `export=` symbol -- an `Assignment` symbol whose declarations are the
+ * assignment itself, or an `Alias | Assignment` onto `f` when `f` is a
+ * function or class -- not to whatever the identifier resolves to lexically.
+ * That synthesis is the checker's module-shape bookkeeping; a value cell is
+ * a question about the lexical declaration, and for these names that is
+ * Node's wrapper parameter, declared by the host. The scope chain of a
+ * JavaScript file still answers with the file's `ModuleExports` symbol, so
+ * when it does the global scope is asked directly. Null when the checker's
+ * answer was not that synthesis, or nothing lexical declares the name.
+ */
+const lexicalSymbolBehindExportSynthesis = (checker, node, symbol) => {
+    if ((symbol.flags & (ts.SymbolFlags.Assignment | ts.SymbolFlags.ModuleExports)) === 0)
+        return null;
+    if ((symbol.declarations ?? []).some((declaration) => ts.isVariableDeclaration(declaration) || ts.isParameter(declaration)))
+        return null;
+    const scoped = checker.resolveName(node.text, node, ts.SymbolFlags.Value, false);
+    const lexical = scoped !== undefined && (scoped.flags & (ts.SymbolFlags.ModuleExports | ts.SymbolFlags.Assignment)) === 0
+        ? scoped
+        : checker.resolveName(node.text, undefined, ts.SymbolFlags.Value, false);
+    return lexical ?? null;
+};
+/**
+ * Whether every declaration of `symbol` is an ambient, initializer-less
+ * `var` whose declared type is the type query `typeof globalThis`. A
+ * declaration with an initializer, or a non-ambient one, allocates its own
+ * cell and stays a binding; a type other than the singleton's own says the
+ * value merely resembles it.
+ */
+/**
+ * Whether `node` sits in an ambient context: a declaration file, or under a
+ * `declare` modifier on itself or an enclosing statement/namespace (`declare
+ * global { var global: typeof globalThis }` puts the modifier on the block,
+ * not the `var`). The checker's own `Ambient` node flag is internal API.
+ */
+const isInAmbientContext = (node) => {
+    if (node.getSourceFile().isDeclarationFile)
+        return true;
+    for (let current = node; current !== undefined; current = current.parent) {
+        if (ts.canHaveModifiers(current) && (ts.getCombinedModifierFlags(current) & ts.ModifierFlags.Ambient) !== 0)
+            return true;
+    }
+    return false;
+};
+const isAmbientAliasOfGlobalThis = (symbol) => {
+    const declarations = symbol.declarations ?? [];
+    if (declarations.length === 0)
+        return false;
+    return declarations.every((declaration) => ts.isVariableDeclaration(declaration) &&
+        declaration.initializer === undefined &&
+        isInAmbientContext(declaration) &&
+        declaration.type !== undefined &&
+        ts.isTypeQueryNode(declaration.type) &&
+        ts.isIdentifier(declaration.type.exprName) &&
+        declaration.type.exprName.text === 'globalThis');
+};
+export const censusUnresolvableNames = (checker, files) => {
+    const withoutCell = new Set();
+    const intrinsicGlobalThis = new Set();
+    const visit = (node) => {
+        // Only identifiers, and only where one could denote a binding at all. A
+        // type position, a property key and a declaration's own name all resolve
+        // through machinery that has nothing to do with a value cell, and asking
+        // about them would put nodes in this set that no reference producer ever
+        // reaches.
+        if (ts.isIdentifier(node) && !ts.isTypeReferenceNode(node.parent)) {
+            const symbol = valueSymbolAt(checker, node);
+            if (symbol === undefined)
+                withoutCell.add(node);
+            // TypeScript creates `globalThis` as a synthetic value symbol whose own
+            // declaration list is empty. It is neither an unresolvable name nor an
+            // ambient cell a host can define. Record that checker fact once so the
+            // reference producer and every citation predictor agree on the direct
+            // value result it publishes. A program binding named `globalThis` has a
+            // declaration and therefore stays an ordinary binding.
+            else if (node.text === 'globalThis' && symbol.name === 'globalThis' && (symbol.declarations?.length ?? 0) === 0) {
+                intrinsicGlobalThis.add(node);
+            }
+            // Node's `global` (and any other name a declaration file spells as
+            // `declare var x: typeof globalThis` with no initializer) is the SAME
+            // singleton, not a second cell: ECMA-262 9.3 gives a realm exactly one
+            // global object, and an ambient `var` typed as THE type of that object,
+            // with nothing to initialize it, states that it is that object under
+            // another name -- `@types/node`'s own spelling is precisely this. Read
+            // as an ordinary ambient binding it becomes an `extern` the emitter
+            // expects a host to define, and no host does: `@hono/node-server`'s
+            // `global.Request !== LightweightRequest` linked against an undefined
+            // `_global`. So the alias publishes the same direct value result the
+            // intrinsic does, and every consumer (the reference producer, the
+            // global-host-mutation census) sees one object.
+            // A declaration's own name is where the alias is SPELLED, not a read
+            // of the object; counting it would make the ambient `var` itself look
+            // like the global object escaping into a binding.
+            else if (!(ts.isVariableDeclaration(node.parent) && node.parent.name === node) && isAmbientAliasOfGlobalThis(symbol)) {
+                intrinsicGlobalThis.add(node);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    for (const file of files)
+        if (!file.isDeclarationFile)
+            visit(file);
+    return {
+        hasNoCell: (node) => withoutCell.has(node),
+        isIntrinsicGlobalThis: (node) => intrinsicGlobalThis.has(node),
+        count: withoutCell.size
+    };
+};

package/dist/semantics/package-sources.d.ts

@@ -0,0 +1,16 @@
+import ts from 'typescript';
+export interface PackageSource {
+    readonly root: string;
+    /** Installed location whose dependency search this checkout inherits. */
+    readonly origin?: string;
+}
+/**
+ * Source discovery is a filesystem view shared by installed packages and source
+ * checkouts. Only package/build metadata supplies an output-to-input mapping;
+ * exports still decide whether the requested subpath is public.
+ */
+export declare const createPackageSourceHost: (host: ts.ModuleResolutionHost, packages?: readonly PackageSource[]) => {
+    host: ts.ModuleResolutionHost;
+    sourceOf: (file: string) => string;
+    containingFile: (specifier: string, containingFile: string) => string;
+};