@geastack/compiler 1.0.15

package/dist/semantics/commonjs-wrapper.js

@@ -0,0 +1,231 @@
+import { resolve } from 'node:path';
+import ts from 'typescript';
+import { valueSymbolAt } from './normalize/unresolvable-names.js';
+const resolvedSymbolAt = (checker, node) => {
+    // One rule for what a name in value position denotes (`valueSymbolAt`),
+    // including checked JavaScript's `module`/`exports`, which the checker binds
+    // to the file's own export synthesis rather than to the wrapper parameter
+    // the host declared. Provenance is a question about that lexical
+    // declaration, and the reference producer keys the same declaration.
+    const local = valueSymbolAt(checker, node);
+    if (!local)
+        return null;
+    return (local.flags & ts.SymbolFlags.Alias) !== 0 ? checker.getAliasedSymbol(local) : local;
+};
+export const commonJsWrapperVariableOf = (node) => {
+    if (ts.isVariableDeclaration(node))
+        return node;
+    for (let current = node; current; current = current.parent) {
+        if (ts.isVariableDeclaration(current))
+            return current;
+        if (ts.isSourceFile(current) || ts.isFunctionLike(current))
+            return null;
+    }
+    return null;
+};
+/** Whether a `var` declaration shares the outer CommonJS wrapper's VariableEnvironment. */
+export const isCommonJsWrapperVarDeclaration = (node) => {
+    if (node.getSourceFile().isDeclarationFile)
+        return false;
+    const list = node.parent;
+    if (!ts.isVariableDeclarationList(list) || (list.flags & ts.NodeFlags.BlockScoped) !== 0)
+        return false;
+    for (let current = list.parent; current; current = current.parent) {
+        if (ts.isSourceFile(current))
+            return true;
+        if (ts.isFunctionLike(current) || ts.isClassStaticBlockDeclaration(current) || ts.isModuleBlock(current))
+            return false;
+    }
+    return false;
+};
+export const commonJsBindingIdentifiers = (name) => {
+    if (ts.isIdentifier(name))
+        return [name];
+    return name.elements.flatMap((element) => (ts.isOmittedExpression(element) ? [] : commonJsBindingIdentifiers(element.name)));
+};
+const exactConfiguredDeclaration = (declaration, configured) => {
+    if (resolve(declaration.getSourceFile().fileName) !== resolve(configured.declarationFileName))
+        return false;
+    return ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) && declaration.name.text === configured.declarationName;
+};
+const exactCompatibleDeclaration = (declaration, configured) => (configured.compatibleDeclarations ?? []).some((compatible) => resolve(declaration.getSourceFile().fileName) === resolve(compatible.declarationFileName) &&
+    ts.isVariableDeclaration(declaration) &&
+    ts.isIdentifier(declaration.name) &&
+    declaration.name.text === compatible.declarationName);
+/**
+ * A lexical `var` only aliases Node's wrapper parameter when the compiler has
+ * already classified this source as CommonJS.  Syntax is deliberately not
+ * enough: the same declaration in an `.mjs` file or a `type: module` package
+ * owns a distinct local binding.
+ *
+ * The checker fills `impliedNodeFormat` only under Node16/NodeNext module
+ * resolution; this compiler resolves as a bundler (`program.ts`), so the
+ * field was never set and every source read as "format unknown", which the
+ * rule below answers as "not a wrapper" -- no `var require` in a `type:
+ * commonjs` package ever authenticated. The fact itself does not depend on
+ * the resolution mode: it is the nearest package.json's `type`, or the
+ * `.cjs`/`.mjs` extension, decided exactly as Node's loader decides it. So
+ * the same walk is asked of TypeScript directly, under the one mode that
+ * makes it answer. A file the walk cannot place still answers nothing, and
+ * nothing is never CommonJS.
+ */
+export const isCommonJsSourceFile = (file, formats) => {
+    let format = file.impliedNodeFormat;
+    if (format === undefined) {
+        if (formats.has(file))
+            format = formats.get(file);
+        else {
+            format = ts.getImpliedNodeFormatForFile(file.fileName, undefined, ts.sys, { moduleResolution: ts.ModuleResolutionKind.NodeNext });
+            formats.set(file, format);
+        }
+    }
+    return format === ts.ModuleKind.CommonJS;
+};
+/**
+ * The program's source text with every bare top-level `var` redeclaration of
+ * a wrapper name blanked, keyed by resolved file name, for the CommonJS files
+ * that carry one.
+ *
+ * `var require` at the top of a CommonJS module is what Node's own wrapper
+ * makes of it: a function-scoped redeclaration of the wrapper's parameter,
+ * which changes nothing at run time -- the name still holds the loader's
+ * `require`. TypeScript reads the same statement as a module-local `var` with
+ * no initializer and, under `strict`, gives it the evolving type every read
+ * sees as `undefined`: `const load = require; load('./x')` is then TS18048
+ * and TS2722, and `load`'s carrier is typed from nothing. The checker cannot
+ * be told that a local redeclares an outer parameter, so the statement is
+ * blanked before the final program is built: the identifier then resolves to
+ * the host's authenticated global declaration, which is what it names.
+ *
+ * Blanked rather than cut so every other position in the file is unchanged
+ * (`diagnostic-source-preparation.ts` makes the same choice). Only the bare
+ * form qualifies: an initializer is a real write the wrapper identity must
+ * see and refuse, a type annotation is the author's own statement about the
+ * name, an exported declaration is a module's surface, and a `var` inside a
+ * function is a different binding altogether. An ESM file is left alone --
+ * there the `var` is a genuine local the identity layer must NOT authenticate.
+ */
+export const withoutBareWrapperRedeclarations = (program, globals, prepared) => {
+    const blanked = new Map();
+    if (globals.size === 0)
+        return blanked;
+    const formats = new Map();
+    for (const file of program.getSourceFiles()) {
+        if (file.isDeclarationFile || !isCommonJsSourceFile(file, formats))
+            continue;
+        const spans = [];
+        for (const statement of file.statements) {
+            if (!ts.isVariableStatement(statement) || statement.modifiers?.length)
+                continue;
+            if ((statement.declarationList.flags & ts.NodeFlags.BlockScoped) !== 0)
+                continue;
+            const bare = statement.declarationList.declarations.every((declaration) => ts.isIdentifier(declaration.name) &&
+                globals.has(declaration.name.text) &&
+                declaration.initializer === undefined &&
+                declaration.type === undefined);
+            if (bare)
+                spans.push({ at: statement.getStart(file), end: statement.getEnd() });
+        }
+        if (spans.length === 0)
+            continue;
+        const fileName = resolve(file.fileName);
+        let text = prepared.get(fileName) ?? file.text;
+        for (const span of [...spans].sort((a, b) => b.at - a.at))
+            text = text.slice(0, span.at) + text.slice(span.at, span.end).replace(/[^\n\r]/g, ' ') + text.slice(span.end);
+        blanked.set(fileName, text);
+    }
+    return blanked;
+};
+const wrapperRedeclarationFor = (declaration, configured, formats) => {
+    const variable = commonJsWrapperVariableOf(declaration);
+    if (variable === null || !isCommonJsSourceFile(variable.getSourceFile(), formats) || !isCommonJsWrapperVarDeclaration(variable))
+        return false;
+    return commonJsBindingIdentifiers(variable.name).some((identifier) => identifier.text === configured.declarationName);
+};
+/**
+ * One authentication result shared by host binding and static-require analysis.
+ * The configured path and declaration spelling establish the host identity;
+ * module-scope `var` declarations may join it only because Node's wrapper has
+ * already introduced that exact parameter cell. No block binding, nested var,
+ * local function, import, or caller-owned ambient declaration is admitted.
+ */
+export const createCommonJsWrapperIdentity = (checker, files, globals) => {
+    const configuredByName = new Map();
+    for (const [name, configured] of globals) {
+        if (name === configured.declarationName && name === configured.global)
+            configuredByName.set(name, configured);
+    }
+    const authenticatedSymbols = new Map();
+    const failedSymbols = new Set();
+    const formats = new Map();
+    for (const file of files) {
+        const visit = (node) => {
+            if (ts.isIdentifier(node) && ts.isVariableDeclaration(node.parent) && node.parent.name === node) {
+                const configured = configuredByName.get(node.text);
+                if (configured && exactConfiguredDeclaration(node.parent, configured)) {
+                    const symbol = resolvedSymbolAt(checker, node);
+                    if (symbol) {
+                        const declarations = symbol.declarations ?? [];
+                        const complete = declarations.length > 0 &&
+                            declarations.every((declaration) => exactConfiguredDeclaration(declaration, configured) ||
+                                exactCompatibleDeclaration(declaration, configured) ||
+                                wrapperRedeclarationFor(declaration, configured, formats));
+                        if (complete)
+                            authenticatedSymbols.set(symbol, configured.global);
+                        else
+                            failedSymbols.add(symbol);
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        if ([...configuredByName.values()].some((configured) => resolve(configured.declarationFileName) === resolve(file.fileName)))
+            visit(file);
+    }
+    const authenticatedGlobals = new Set(authenticatedSymbols.values());
+    const redeclarations = new Map();
+    const declarationGlobals = new Map();
+    for (const file of files) {
+        if (file.isDeclarationFile || !isCommonJsSourceFile(file, formats))
+            continue;
+        const visit = (node) => {
+            if (ts.isVariableDeclaration(node) && isCommonJsWrapperVarDeclaration(node)) {
+                for (const identifier of commonJsBindingIdentifiers(node.name)) {
+                    const configured = configuredByName.get(identifier.text);
+                    if (!configured || !authenticatedGlobals.has(configured.global))
+                        continue;
+                    const symbol = resolvedSymbolAt(checker, identifier);
+                    if (!symbol)
+                        continue;
+                    const perFile = new Map(redeclarations.get(symbol) ?? []);
+                    perFile.set(file, configured.global);
+                    redeclarations.set(symbol, perFile);
+                    const declaration = identifier === node.name ? node : identifier.parent;
+                    if (ts.isVariableDeclaration(declaration) || ts.isBindingElement(declaration)) {
+                        declarationGlobals.set(declaration, configured.global);
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+    }
+    const classify = (identifier) => {
+        const symbol = resolvedSymbolAt(checker, identifier);
+        if (!symbol)
+            return { kind: 'ordinary' };
+        const redeclared = redeclarations.get(symbol)?.get(identifier.getSourceFile());
+        if (redeclared !== undefined)
+            return { kind: 'wrapper', global: redeclared };
+        const authenticated = authenticatedSymbols.get(symbol);
+        if (authenticated !== undefined)
+            return { kind: 'wrapper', global: authenticated };
+        if (failedSymbols.has(symbol))
+            return { kind: 'provenance-failure' };
+        return { kind: 'ordinary' };
+    };
+    return {
+        classify,
+        globalOfDeclaration: (declaration) => declarationGlobals.get(declaration) ?? null
+    };
+};

package/dist/semantics/constructor-slot-subclasses.d.ts

@@ -0,0 +1,28 @@
+import ts from 'typescript';
+import type { DeclarationId } from '../identity/ids.js';
+import type { IdentityTable } from './normalize/identities.js';
+/**
+ * Which DERIVED class constructors the program stores into a slot typed as a
+ * base class's constructor, keyed by the base.
+ *
+ * `typeof Base` is the checker's type for the `Base` identifier AND for any
+ * cell declared with it, and `representation/derive.ts` gives it a
+ * constructor family whose one member is `Base`. That member list is a
+ * promise every consumer cashes: construction inlines `Base`'s initializer
+ * (`ir/native-class-construction.ts`), static reads resolve to `Base`'s
+ * members. `var Request: typeof RequestImpl = RequestImpl`, later replaced by
+ * `@hono/node-server`'s own subclass, breaks the promise -- `new Request()`
+ * must build the subclass -- so the family has to name every class the
+ * program can put there, and that is a fact about the program's WRITES, which
+ * only this layer can see.
+ *
+ * A write is: a value position whose contextual type is `typeof Base`
+ * (an assignment, an annotated initializer, an argument, a return, an object
+ * literal property), plus `Object.defineProperty(G, 'K', { value: V })`,
+ * whose descriptor's `value` is `any` to the checker but lands in `G.K`, typed
+ * by `G`'s own declaration. Only a PROPER subclass is recorded: an unrelated
+ * class of the same shape has no base subobject to upcast through, so its
+ * store stays refused by the conversion census rather than being admitted
+ * here.
+ */
+export declare const constructorSlotSubclassesOf: (checker: ts.TypeChecker, identities: IdentityTable, files: readonly ts.SourceFile[], heritage: ReadonlyMap<DeclarationId, readonly DeclarationId[]>) => ReadonlyMap<DeclarationId, readonly DeclarationId[]>;

package/dist/semantics/constructor-slot-subclasses.js

@@ -0,0 +1,112 @@
+import ts from 'typescript';
+/**
+ * Which DERIVED class constructors the program stores into a slot typed as a
+ * base class's constructor, keyed by the base.
+ *
+ * `typeof Base` is the checker's type for the `Base` identifier AND for any
+ * cell declared with it, and `representation/derive.ts` gives it a
+ * constructor family whose one member is `Base`. That member list is a
+ * promise every consumer cashes: construction inlines `Base`'s initializer
+ * (`ir/native-class-construction.ts`), static reads resolve to `Base`'s
+ * members. `var Request: typeof RequestImpl = RequestImpl`, later replaced by
+ * `@hono/node-server`'s own subclass, breaks the promise -- `new Request()`
+ * must build the subclass -- so the family has to name every class the
+ * program can put there, and that is a fact about the program's WRITES, which
+ * only this layer can see.
+ *
+ * A write is: a value position whose contextual type is `typeof Base`
+ * (an assignment, an annotated initializer, an argument, a return, an object
+ * literal property), plus `Object.defineProperty(G, 'K', { value: V })`,
+ * whose descriptor's `value` is `any` to the checker but lands in `G.K`, typed
+ * by `G`'s own declaration. Only a PROPER subclass is recorded: an unrelated
+ * class of the same shape has no base subobject to upcast through, so its
+ * store stays refused by the conversion census rather than being admitted
+ * here.
+ */
+export const constructorSlotSubclassesOf = (checker, identities, files, heritage) => {
+    const subclasses = new Map();
+    // The static side of a class only: `typeof C` is the type of the class
+    // symbol's value, while the instance type shares the symbol.
+    const classOfConstructorType = (type) => {
+        const symbol = type.getSymbol();
+        if (!symbol || (symbol.flags & ts.SymbolFlags.Class) === 0)
+            return null;
+        const node = symbol.declarations?.find((candidate) => ts.isClassLike(candidate));
+        if (!node || checker.getTypeOfSymbol(symbol) !== type)
+            return null;
+        return identities.declarationIdOf(node);
+    };
+    const record = (target, source) => {
+        if (!target)
+            return;
+        const derived = classOfConstructorType(checker.getTypeAtLocation(source));
+        if (derived === null)
+            return;
+        const ancestors = heritage.get(derived) ?? [];
+        for (const arm of target.isUnion() ? target.types : [target]) {
+            const base = classOfConstructorType(arm);
+            if (base === null || base === derived || !ancestors.includes(base))
+                continue;
+            const known = subclasses.get(base) ?? [];
+            if (!known.includes(derived))
+                known.push(derived);
+            subclasses.set(base, known);
+        }
+    };
+    const isObjectDefineProperty = (call) => {
+        const callee = call.expression;
+        return (ts.isPropertyAccessExpression(callee) &&
+            callee.name.text === 'defineProperty' &&
+            ts.isIdentifier(callee.expression) &&
+            callee.expression.text === 'Object');
+    };
+    const recordDefinedValue = (call) => {
+        const [holder, key, descriptor] = call.arguments;
+        if (!holder || !key || !descriptor || !ts.isStringLiteralLike(key) || !ts.isObjectLiteralExpression(descriptor))
+            return;
+        const value = descriptor.properties.find((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'value');
+        if (!value)
+            return;
+        const slot = checker.getPropertyOfType(checker.getTypeAtLocation(holder), key.text);
+        if (slot)
+            record(checker.getTypeOfSymbolAtLocation(slot, call), value.initializer);
+    };
+    // The source is looked at only where a constructor can plausibly be named;
+    // asking the checker for every expression's type would cost the whole walk.
+    const isNamedValue = (node) => {
+        let inner = node;
+        while (ts.isParenthesizedExpression(inner))
+            inner = inner.expression;
+        return ts.isIdentifier(inner) || ts.isPropertyAccessExpression(inner) || ts.isClassExpression(inner);
+    };
+    const valuePosition = (node) => {
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken)
+            return node.right;
+        if (ts.isVariableDeclaration(node) && node.type && node.initializer)
+            return node.initializer;
+        if (ts.isPropertyDeclaration(node) && node.type && node.initializer)
+            return node.initializer;
+        if (ts.isReturnStatement(node) && node.expression)
+            return node.expression;
+        if (ts.isPropertyAssignment(node))
+            return node.initializer;
+        return null;
+    };
+    for (const file of files) {
+        const visit = (node) => {
+            const value = valuePosition(node);
+            if (value && isNamedValue(value))
+                record(checker.getContextualType(value), value);
+            if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+                for (const argument of node.arguments ?? [])
+                    if (isNamedValue(argument))
+                        record(checker.getContextualType(argument), argument);
+                if (ts.isCallExpression(node) && isObjectDefineProperty(node))
+                    recordDefinedValue(node);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(file);
+    }
+    return subclasses;
+};

package/dist/semantics/declaration-overlay-transform.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Whether a declared parameter type leaves a position INSIDE it unstated -- an
+ * `any`/`unknown` array element, type argument, or member.
+ *
+ * `STATES_NOTHING` catches the bare spelling; this catches the same silence one
+ * level down, and it matters for the same reason. `WebGLPrograms.d.ts` states
+ * `getParameters( ..., lights: WebGLLightsState, ..., lightProbeGrids:
+ * unknown[] )`, and `WebGLLightsState` states `probe: unknown[]`,
+ * `directional: unknown[]`. Transferred, each is a STATEMENT, so the census
+ * never derives the parameter from its call site -- yet the one call site
+ * passes `lights.state` and `lightProbeGridArray` whose elements the program
+ * DOES type (`Vector3`, the uniform classes, `NativeLightProbeGrid`). The
+ * argument is then a typed array and the parameter an array of dynamic
+ * elements, the element layouts differ, and no conversion exists or should:
+ * measured on the three.js app, those two parameters were two of the three certificate
+ * refusals. The package said nothing about those elements, so the overlay says
+ * nothing about the parameter, and the census derives it from what callers
+ * actually pass.
+ *
+ * ⛔ Only DATA positions count: an array/tuple element, a type argument, a
+ * record member's value. A function type is a different statement entirely --
+ * `traverse( callback: ( object: Object3D ) => any )` states the callback's
+ * parameter, which is the CONTEXTUAL type an app's arrow function has no
+ * other source for, and its `any` return says nothing a caller supplies. The
+ * census cannot re-derive a callback's signature from call sites, so dropping
+ * such a statement strips the app's parameter to an implicit `any` (measured:
+ * one app module's `part` parameter became a checker error). Function types,
+ * method members and call/construct signatures are therefore never walked.
+ */
+export declare const statesNothingWithin: (text: string) => boolean;
+export declare const declarationOverlayTransform: (input: {
+    readonly fileName: string;
+    readonly text: string;
+    readonly declarationFileName?: string;
+}) => string | null;