@geastack/compiler 1.0.15

package/dist/semantics/module-resolution.js

@@ -0,0 +1,227 @@
+import ts from 'typescript';
+import { dirname, resolve } from 'node:path';
+import { createPackageSourceHost } from './package-sources.js';
+export const isDeclarationPath = (file) => /\.d\.(?:ts|mts|cts)$/.test(file);
+export const moduleExtension = (file) => {
+    if (file.endsWith('.d.mts'))
+        return ts.Extension.Dmts;
+    if (file.endsWith('.d.cts'))
+        return ts.Extension.Dcts;
+    if (file.endsWith('.d.ts'))
+        return ts.Extension.Dts;
+    if (file.endsWith('.tsx'))
+        return ts.Extension.Tsx;
+    if (file.endsWith('.mts'))
+        return ts.Extension.Mts;
+    if (file.endsWith('.cts'))
+        return ts.Extension.Cts;
+    if (file.endsWith('.mjs'))
+        return ts.Extension.Mjs;
+    if (file.endsWith('.cjs'))
+        return ts.Extension.Cjs;
+    if (file.endsWith('.jsx'))
+        return ts.Extension.Jsx;
+    if (file.endsWith('.js'))
+        return ts.Extension.Js;
+    if (file.endsWith('.json'))
+        return ts.Extension.Json;
+    return ts.Extension.Ts;
+};
+/** The package that owns a resolved file, using the program host's own view. */
+const packageRootOf = (file, host) => {
+    let directory = dirname(resolve(file));
+    for (;;) {
+        if (host.fileExists(`${directory}/package.json`))
+            return directory;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+};
+/**
+ * A declaration may describe an implementation only when the same package
+ * ships both. In particular, `@types/three` is a third party package and must
+ * not replace Three's real JavaScript source, including for type-only imports.
+ */
+const ownedDeclaration = (declaration, implementation, host) => {
+    if (!declaration || !implementation)
+        return declaration;
+    const declaredPackage = packageRootOf(declaration.resolvedFileName, host);
+    const implementedPackage = packageRootOf(implementation.resolvedFileName, host);
+    return declaredPackage !== undefined && declaredPackage === implementedPackage ? declaration : undefined;
+};
+/** Remove type-only lookup metadata, preserving runtime condition order and null exclusions. */
+const runtimeConditions = (value) => {
+    if (Array.isArray(value))
+        return value.map(runtimeConditions);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => key !== 'types' && !key.startsWith('types@'))
+        .map(([key, entry]) => [key, runtimeConditions(entry)]));
+};
+/**
+ * Ask the same resolver two questions, through separate caches. Hiding declarations
+ * only on the implementation view keeps TypeScript's exports/imports, conditions,
+ * paths, package self references, and nested dependency search authoritative.
+ * No package names, source-directory guesses, or package code execution belong here.
+ */
+export const createModuleResolver = (host, options, declarationModules = new Set(), packageSources = []) => {
+    const currentDirectory = host.getCurrentDirectory?.() ?? ts.sys.getCurrentDirectory();
+    const canonical = ts.sys.useCaseSensitiveFileNames ? (file) => file : (file) => file.toLowerCase();
+    const typesCache = ts.createModuleResolutionCache(currentDirectory, canonical, options);
+    const runtimeCache = ts.createModuleResolutionCache(currentDirectory, canonical, options);
+    const sources = createPackageSourceHost(host, packageSources);
+    const manifests = new Map();
+    const runtimeHost = {
+        ...sources.host,
+        fileExists: (file) => !isDeclarationPath(file) && sources.host.fileExists(file),
+        readFile: (file) => {
+            if (!file.endsWith('/package.json'))
+                return sources.host.readFile(file);
+            if (manifests.has(file))
+                return manifests.get(file);
+            const text = sources.host.readFile(file);
+            if (text === undefined)
+                return undefined;
+            let result = text;
+            try {
+                const manifest = JSON.parse(text);
+                if (manifest !== null && typeof manifest === 'object' && !Array.isArray(manifest)) {
+                    const fields = Object.fromEntries(Object.entries(manifest).filter(([key]) => !['types', 'typings', 'typesVersions'].includes(key)));
+                    if ('exports' in fields)
+                        fields.exports = runtimeConditions(fields.exports);
+                    if ('imports' in fields)
+                        fields.imports = runtimeConditions(fields.imports);
+                    result = JSON.stringify(fields);
+                }
+            }
+            catch {
+                // Preserve malformed metadata for the resolver's own diagnostic behaviour.
+            }
+            manifests.set(file, result);
+            return result;
+        }
+    };
+    const nativeModule = (specifier) => declarationModules.has(specifier) ||
+        [...declarationModules].some((pattern) => pattern.endsWith('/*') && specifier.startsWith(pattern.slice(0, -1)));
+    return {
+        resolve: (specifier, containingFile, mode, statedTarget) => {
+            const typed = ts.resolveModuleName(specifier, containingFile, options, host, typesCache, undefined, mode).resolvedModule;
+            const native = nativeModule(specifier);
+            let declaration = typed && isDeclarationPath(typed.resolvedFileName) ? typed : undefined;
+            // A plugin that declares a module native owns its declarations, and the
+            // importing file is not always able to reach them: a package inside the
+            // module graph may import a peer the bundler resolved through the *app's*
+            // node_modules rather than its own, leaving `node_modules/@scope` empty
+            // next to the importer. The file the graph itself resolved to always lives
+            // inside the owning package, so ask again from there before concluding the
+            // declarations are missing -- otherwise the native package's runtime
+            // JavaScript is compiled as ordinary source and its classes collide with
+            // the host-bound ambient ones they shadow.
+            if (native && declaration === undefined && statedTarget !== undefined && !isDeclarationPath(statedTarget)) {
+                const owned = ts.resolveModuleName(specifier, statedTarget, options, host, typesCache, undefined, mode).resolvedModule;
+                if (owned && isDeclarationPath(owned.resolvedFileName))
+                    declaration = owned;
+            }
+            if (native && declaration)
+                return { typeDeclaration: declaration, declaration, implementation: undefined, native };
+            if (statedTarget !== undefined) {
+                const target = { resolvedFileName: statedTarget, extension: moduleExtension(statedTarget), isExternalLibraryImport: false };
+                if (isDeclarationPath(statedTarget))
+                    return { typeDeclaration: target, declaration: target, implementation: undefined, native: true };
+                // Fail closed rather than substituting source for a module a plugin
+                // declared native: no declarations is a broken installation, and the
+                // resulting "cannot find module" names it, where a source overlay would
+                // silently duplicate every host-bound type.
+                if (native)
+                    return { typeDeclaration: undefined, declaration: undefined, implementation: undefined, native };
+                return {
+                    typeDeclaration: declaration,
+                    declaration: ownedDeclaration(declaration, target, host),
+                    implementation: target,
+                    native: false
+                };
+            }
+            // Relative imports inside declaration trees must continue to describe types.
+            // They never cause executable files to be substituted into those trees.
+            if (isDeclarationPath(containingFile)) {
+                return {
+                    typeDeclaration: declaration,
+                    declaration,
+                    implementation: typed && !isDeclarationPath(typed.resolvedFileName) ? typed : undefined,
+                    native
+                };
+            }
+            const resolved = ts.resolveModuleName(specifier, sources.containingFile(specifier, containingFile), options, runtimeHost, runtimeCache, undefined, mode).resolvedModule;
+            const source = resolved ? sources.sourceOf(resolved.resolvedFileName) : undefined;
+            const implementation = resolved && source ? { ...resolved, resolvedFileName: source, extension: moduleExtension(source) } : resolved;
+            return { typeDeclaration: declaration, declaration: ownedDeclaration(declaration, implementation, host), implementation, native };
+        }
+    };
+};
+export const typeOnlyModuleUse = (literal, checker, verbatim = false) => {
+    const erasedBinding = (name) => {
+        if (!checker || verbatim)
+            return false;
+        let symbol = checker.getSymbolAtLocation(name);
+        if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0)
+            symbol = checker.getAliasedSymbol(symbol);
+        return symbol !== undefined && (symbol.flags & ts.SymbolFlags.Value) === 0;
+    };
+    let node = literal.parent;
+    while (node) {
+        if (ts.isImportTypeNode(node) || ts.isJSDocImportTag(node))
+            return true;
+        if (ts.isImportDeclaration(node)) {
+            const clause = node.importClause;
+            if (clause?.isTypeOnly)
+                return true;
+            const bindings = clause?.namedBindings;
+            return ((!clause?.name || erasedBinding(clause.name)) &&
+                bindings !== undefined &&
+                ts.isNamedImports(bindings) &&
+                bindings.elements.length > 0 &&
+                bindings.elements.every((item) => item.isTypeOnly || erasedBinding(item.name)));
+        }
+        if (ts.isExportDeclaration(node)) {
+            return (node.isTypeOnly ||
+                (node.exportClause !== undefined &&
+                    ts.isNamedExports(node.exportClause) &&
+                    node.exportClause.elements.length > 0 &&
+                    node.exportClause.elements.every((item) => item.isTypeOnly || erasedBinding(item.name))));
+        }
+        if (ts.isImportEqualsDeclaration(node))
+            return node.isTypeOnly;
+        node = node.parent;
+    }
+    return false;
+};
+/** A single-file source map is explicit provenance; a directory name is not. */
+export const mappedTypeScriptSource = (file, host) => {
+    if (!/\.(?:js|mjs|cjs|jsx)$/.test(file))
+        return undefined;
+    const text = host.readFile(`${file}.map`);
+    if (text === undefined)
+        return undefined;
+    try {
+        const map = JSON.parse(text);
+        if (map === null || typeof map !== 'object')
+            return undefined;
+        const fields = map;
+        if (!Array.isArray(fields.sources) || fields.sources.length !== 1 || typeof fields.sources[0] !== 'string')
+            return undefined;
+        if (fields.sourceRoot !== undefined && typeof fields.sourceRoot !== 'string')
+            return undefined;
+        const source = fields.sources[0];
+        const root = fields.sourceRoot ?? '';
+        if (/^[a-z]+:/i.test(source) || /^[a-z]+:/i.test(root))
+            return undefined;
+        const target = resolve(dirname(file), root, source);
+        return /\.(?:ts|mts|cts|tsx)$/.test(target) && !isDeclarationPath(target) && host.fileExists(target) ? target : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/semantics/new-callee-class-tag-source-transform.d.ts

@@ -0,0 +1,4 @@
+export declare const newCalleeClassTagSourceTransform: (input: {
+    readonly fileName: string;
+    readonly text: string;
+}) => string | null;

package/dist/semantics/new-callee-class-tag-source-transform.js

@@ -0,0 +1,64 @@
+import ts from 'typescript';
+const isJavaScriptFile = (fileName) => fileName.endsWith('.js') || fileName.endsWith('.mjs') || fileName.endsWith('.cjs');
+const returnsAValue = (body) => body.statements.some((statement) => ts.isReturnStatement(statement) && statement.expression !== undefined);
+const alreadyTagged = (node) => ts.getJSDocTags(node).some((tag) => tag.tagName.text === 'class' || tag.tagName.text === 'constructor');
+/** The functions `new F()` can name in this file, by name: declarations, and `var F = function () {}` initializers. */
+const constructibleFunctionsIn = (file) => {
+    const found = new Map();
+    const visit = (node) => {
+        if (ts.isFunctionDeclaration(node) && node.name && node.body)
+            found.set(node.name.text, node);
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer &&
+            ts.isFunctionExpression(node.initializer) &&
+            node.initializer.body) {
+            found.set(node.name.text, node.initializer);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return found;
+};
+const candidatesIn = (file) => {
+    const functions = constructibleFunctionsIn(file);
+    if (functions.size === 0)
+        return [];
+    const constructed = new Set();
+    const called = new Set();
+    const visit = (node) => {
+        if (ts.isNewExpression(node) && ts.isIdentifier(node.expression))
+            constructed.add(node.expression.text);
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression))
+            called.add(node.expression.text);
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    const found = [];
+    for (const [name, fn] of functions) {
+        if (!constructed.has(name) || called.has(name))
+            continue;
+        if (!fn.body || returnsAValue(fn.body) || alreadyTagged(fn))
+            continue;
+        // Into an existing JSDoc block, never beside it: a second block placed
+        // between a `@param` block and its function detached the first one's
+        // parameter types (the checker read the parameters as implicit `any`).
+        const docs = ts.getJSDocCommentsAndTags(fn).filter(ts.isJSDoc);
+        const last = docs[docs.length - 1];
+        found.push(last ? { at: last.end - 2, text: ' @class ' } : { at: fn.getStart(file), text: '/** @class */ ' });
+    }
+    return found.sort((a, b) => a.at - b.at);
+};
+export const newCalleeClassTagSourceTransform = (input) => {
+    if (!isJavaScriptFile(input.fileName) || !input.text.includes('new '))
+        return null;
+    const file = ts.createSourceFile(input.fileName, input.text, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+    const candidates = candidatesIn(file);
+    if (candidates.length === 0)
+        return null;
+    let rewritten = input.text;
+    for (const candidate of [...candidates].reverse()) {
+        rewritten = `${rewritten.slice(0, candidate.at)}${candidate.text}${rewritten.slice(candidate.at)}`;
+    }
+    return rewritten;
+};

package/dist/semantics/node-project.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+export interface NodeProject {
+    readonly root: string;
+    readonly manifest: Record<string, unknown>;
+    readonly projectFile: string | undefined;
+    readonly entries: readonly {
+        name: string;
+        file: string;
+    }[];
+}
+/** Parse literal launch commands, never run a project's application or shell code. */
+export declare const startEntry: (script: string, scripts: Record<string, unknown>, seen?: Set<string>) => string | undefined;
+export declare const discoverNodeProject: (directory: string, host?: ts.System) => NodeProject;

package/dist/semantics/node-project.js

@@ -0,0 +1,107 @@
+import ts from 'typescript';
+import { dirname, resolve, basename, extname } from 'node:path';
+import { createPackageSourceHost } from './package-sources.js';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+/** Parse literal launch commands, never run a project's application or shell code. */
+export const startEntry = (script, scripts, seen = new Set()) => {
+    if (/[;&|`$<>\n]/.test(script))
+        return undefined;
+    const words = script.match(/"[^"\n]*"|'[^'\n]*'|[^\s]+/g)?.map((word) => word.replace(/^(['"])(.*)\1$/, '$2')) ?? [];
+    while (words[0] && /^[\w]+=[^\s]*$/.test(words[0]))
+        words.shift();
+    if (words[0] === 'cross-env')
+        words.shift();
+    while (words[0] && /^[\w]+=[^\s]*$/.test(words[0]))
+        words.shift();
+    const launcher = words.shift();
+    if (['npm', 'pnpm', 'yarn'].includes(launcher ?? '')) {
+        if (words[0] === 'run')
+            words.shift();
+        const name = words[0];
+        if (!name || seen.has(name) || typeof scripts[name] !== 'string')
+            return undefined;
+        seen.add(name);
+        return startEntry(scripts[name], scripts, seen);
+    }
+    if (!['node', 'tsx', 'ts-node', 'ts-node-esm'].includes(launcher ?? ''))
+        return undefined;
+    const takesValue = new Set(['--require', '-r', '--import', '--loader', '--experimental-loader', '--conditions', '-C', '--project', '-P']);
+    while (words[0]?.startsWith('-')) {
+        const flag = words.shift();
+        if (['-e', '--eval', '-p', '--print', '--test'].includes(flag))
+            return undefined;
+        if (takesValue.has(flag))
+            words.shift();
+    }
+    return words[0];
+};
+export const discoverNodeProject = (directory, host = ts.sys) => {
+    let root = resolve(directory);
+    while (!host.fileExists(resolve(root, 'package.json'))) {
+        const parent = dirname(root);
+        if (parent === root)
+            throw new Error(`No package.json found from ${directory}`);
+        root = parent;
+    }
+    const manifest = object(JSON.parse(host.readFile(resolve(root, 'package.json'))));
+    const projectFile = ts.findConfigFile(root, host.fileExists);
+    const sources = createPackageSourceHost(host);
+    const entryFile = (value) => {
+        if (typeof value !== 'string' || value.includes('*'))
+            return undefined;
+        const file = sources.sourceOf(resolve(root, value));
+        if (host.fileExists(file) && !/\.d\.[cm]?ts$/.test(file))
+            return file;
+        if (!extname(file)) {
+            const candidates = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'].map((extension) => file + extension).filter(host.fileExists);
+            if (candidates.length === 1)
+                return candidates[0];
+        }
+        return undefined;
+    };
+    const name = typeof manifest.name === 'string' ? manifest.name.split('/').pop() : basename(root);
+    const scripts = object(manifest.scripts);
+    const launch = typeof scripts.start === 'string' ? startEntry(scripts.start, scripts) : undefined;
+    const launched = entryFile(launch);
+    if (launched)
+        return { root, manifest, projectFile, entries: [{ name, file: launched }] };
+    if (launch)
+        throw new Error(`The start script names ${launch}, but neither it nor its declared source exists.`);
+    const bins = typeof manifest.bin === 'string' ? { [name]: manifest.bin } : object(manifest.bin);
+    if (Object.keys(bins).length > 0) {
+        const entries = Object.entries(bins).map(([name, value]) => {
+            const file = entryFile(value);
+            if (!file)
+                throw new Error(`Cannot find the source for package bin ${name}: ${String(value)}`);
+            return { name, file };
+        });
+        return { root, manifest, projectFile, entries };
+    }
+    const publicEntry = (value) => {
+        const direct = entryFile(value);
+        if (direct)
+            return direct;
+        const fields = object(value);
+        if ('.' in fields)
+            return publicEntry(fields['.']);
+        for (const [key, target] of Object.entries(fields)) {
+            if (!['node', 'import', 'require', 'default'].includes(key))
+                continue;
+            const file = publicEntry(target);
+            if (file)
+                return file;
+        }
+        return undefined;
+    };
+    const main = publicEntry(manifest.exports) ?? entryFile(manifest.main) ?? entryFile(manifest.source);
+    if (main)
+        return { root, manifest, projectFile, entries: [{ name, file: main }] };
+    const conventional = ['src/index', 'src/main', 'src/server', 'index', 'main', 'server']
+        .flatMap((stem) => ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs'].map((extension) => resolve(root, stem + extension)))
+        .filter(host.fileExists);
+    if (conventional.length === 1)
+        return { root, manifest, projectFile, entries: [{ name, file: conventional[0] }] };
+    throw new Error(conventional.length > 1
+        ? `Ambiguous application entry: ${conventional.join(', ')}. Declare scripts.start or bin in package.json.`
+        : 'No executable entry was found. Declare scripts.start, bin, or main in package.json.');
+};

package/dist/semantics/node-source-hooks.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/semantics/node-source-hooks.js

@@ -0,0 +1,63 @@
+// The corpus oracle asks the compiler's resolver which source implements an
+// import, then lets Node/tsx execute it. It never borrows the native host shims.
+import { registerHooks, isBuiltin } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolve, dirname, sep } from 'node:path';
+import ts from 'typescript';
+import { createModuleResolver } from './module-resolution.js';
+import { defaultCompilerOptions } from './program.js';
+const serialized = process.env.GEATSC_SOURCE_CONTEXT;
+if (serialized) {
+    const context = JSON.parse(serialized);
+    let options = { ...defaultCompilerOptions, types: [] };
+    if (context.projectFile) {
+        const config = ts.readConfigFile(context.projectFile, ts.sys.readFile);
+        if (config.error)
+            throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'));
+        options = { ...options, ...ts.parseJsonConfigFileContent(config.config, ts.sys, dirname(context.projectFile)).options };
+    }
+    const resolver = createModuleResolver(ts.sys, options, new Set(), context.packageSources);
+    const selected = new Set();
+    const roots = [resolve(context.root), ...context.packageSources.map((source) => resolve(source.root))];
+    const inSource = (url) => {
+        if (!url?.startsWith('file:'))
+            return false;
+        const file = fileURLToPath(url);
+        return selected.has(url) || roots.some((root) => file === root || file.startsWith(`${root}${sep}`));
+    };
+    registerHooks({
+        resolve(specifier, hookContext, nextResolve) {
+            if (isBuiltin(specifier) || (!inSource(hookContext.parentURL) && !inSource(specifier)))
+                return nextResolve(specifier, hookContext);
+            if (specifier.startsWith('file:') && (specifier.includes('?') || specifier.includes('#')))
+                return nextResolve(specifier, hookContext);
+            const from = hookContext.parentURL?.startsWith('file:') ? fileURLToPath(hookContext.parentURL) : resolve(context.root, '__entry__.ts');
+            const name = specifier.startsWith('file:') ? fileURLToPath(specifier) : specifier;
+            const mode = hookContext.conditions.includes('require') ? ts.ModuleKind.CommonJS : ts.ModuleKind.ESNext;
+            const result = resolver.resolve(name, from, mode).implementation;
+            if (!result)
+                return nextResolve(specifier, hookContext);
+            const url = pathToFileURL(result.resolvedFileName).href;
+            selected.add(url);
+            return nextResolve(url, hookContext);
+        },
+        load(url, hookContext, nextLoad) {
+            if (!selected.has(url) || !/\.[cm]?tsx?$/.test(fileURLToPath(url)))
+                return nextLoad(url, hookContext);
+            const file = fileURLToPath(url);
+            const source = ts.sys.readFile(file);
+            if (source === undefined)
+                throw new Error(`Source disappeared: ${file}`);
+            const ast = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+            const commonJS = file.endsWith('.cts') || ast.statements.some((statement) => ts.isExportAssignment(statement) && statement.isExportEquals);
+            // A source checkout may have type:commonjs while its published import
+            // branch is ESM. Transpile the source module itself; package-scope format
+            // inference would add a spurious second default export around it.
+            const transformed = ts.transpileModule(source, {
+                fileName: file,
+                compilerOptions: { ...options, module: commonJS ? ts.ModuleKind.CommonJS : ts.ModuleKind.ESNext, noEmit: false, declaration: false }
+            });
+            return { format: commonJS ? 'commonjs' : 'module', source: transformed.outputText, shortCircuit: true };
+        }
+    });
+}

package/dist/semantics/normalize/absent-globals.d.ts

@@ -0,0 +1,143 @@
+import ts from 'typescript';
+import type { NamespacePathCensus } from './namespace-paths.js';
+/**
+ * The ambient globals an installed host declares it does NOT provide.
+ *
+ * An ambient declaration is a contract with a host: `declare var VideoFrame:
+ * {...}` says something out there defines this. TypeScript has no way to say
+ * the opposite, so a compiler with no other source of truth believes every one
+ * of them -- and that belief is a measured silent miscompile. `typeof
+ * VideoFrame !== 'undefined'` folds to `true` because the value's carrier is a
+ * constructor, while the same unit emits `extern gea::ConstructorObject<...>
+ * VideoFrame;` for a symbol no object file defines. The program is told a value
+ * exists, takes the branch that reads `image.displayWidth` off something that
+ * is not a `VideoFrame`, and the failure lands in the linker or at runtime
+ * rather than here.
+ *
+ * three.js is written to run where these may not exist and says so in its own
+ * source, guarding every one with `typeof X !== 'undefined'`. A native ANGLE
+ * context is exactly such a place. `PluginCapabilities.absentGlobals` is where
+ * a host states it; this turns that statement into the one thing the rest of
+ * the compiler already knows how to reason about -- the type `undefined`.
+ *
+ * ## Why the type, and not a refusal or a carrier
+ *
+ * `undefined` is the language's OWN answer for a global that is not there, and
+ * every stage downstream already handles it: `typeof` yields `'undefined'`, the
+ * guard's other branch is dead, the binding is not external so no `extern` is
+ * emitted, and a program that reads the value anyway is refused by the ordinary
+ * rules for reading `undefined` rather than by a special case invented here.
+ *
+ * Refusing instead would reject a program that is correct precisely because it
+ * checked, which is the opposite of what the guard is for.
+ *
+ * ## One authority
+ *
+ * Answering the DECLARATION and every REFERENCE from the same table is the
+ * whole of it. A binding whose declaration said `undefined` while its
+ * references said `VideoFrameConstructor` would be two carriers for one cell --
+ * the defect shape this compiler has paid for repeatedly. Both routes go
+ * through `typeAt` below.
+ *
+ * A host that states nothing gets `emptyAbsentGlobalCensus`, whose `typeAt` is
+ * `() => null`, and nothing about such a program changes.
+ */
+export interface AbsentGlobalCensus {
+    /**
+     * `undefined` when this node reads a global a host declared absent, or `null`
+     * when nothing here improves on the checker's answer.
+     *
+     * `null` is the normal case: the census answers only for names an installed
+     * host actually listed.
+     */
+    readonly typeAt: (node: ts.Node) => ts.Type | null;
+    /**
+     * `type`, unless it names an ambient TYPE a host declared absent -- in which
+     * case `never`.
+     *
+     * `absentGlobals` is a fact about a VALUE (`typeAt` above): a host saying
+     * `HTMLImageElement` is absent says the *constructor* is not there. It says
+     * nothing yet about the TYPE `HTMLImageElement` -- the interface a program's
+     * own ambient declarations (three.js's JSDoc `@param
+     * {(HTMLImageElement|HTMLCanvasElement)} image`, straight off lib.dom) can
+     * still name in a position this compiler never asked the value for. This is
+     * that missing type-level counterpart, built the same way and for the same
+     * reason: no ambient VALUE means no way for a program running on this host to
+     * ever hold a value of that ambient TYPE either, so a position typed
+     * (in part) that way can be told the arm is `never` -- the language's own
+     * empty type, which every existing consumer of a structural union already
+     * drops before building an arm (`representation/union.ts`'s `isNever`).
+     *
+     * Deliberately a `ts.Type -> ts.Type` function and not an attempt to hand
+     * back a narrowed union: `ts.TypeChecker.getUnionType` is not on the public
+     * surface (`producers/bindings.ts`'s `withoutUndefinedMember` hit the same
+     * wall and solved it the same way -- filter the STRUCTURAL union instead of
+     * reconstructing a `ts.Type`). Applying this to each member of a union
+     * *before* it is interned needs no such reconstruction at all: every member
+     * is already its own independent `ts.Type`, `getNeverType()` is public, and
+     * a member that becomes `never` is dropped by the existing structural rule
+     * with no new plumbing. See `structural.ts`'s union case for where this
+     * wants to be called -- `type.types.map(typeOf)` becomes
+     * `type.types.map((member) => typeOf(absent.substituteAbsentType(member)))`.
+     *
+     * Resolution is by SYMBOL, exactly as `typeAt` resolves by symbol rather
+     * than by spelling: only a type whose OWN declaration is the standard
+     * library's ambient one is answered, so a program's own same-named type is
+     * untouched. Idempotent and total on every `ts.Type` -- it is safe to call
+     * on anything, including a type that is not an object type at all, and it
+     * always returns a real type rather than `null`, because unlike `typeAt`
+     * there is no "no answer" case: the type is either named-absent or it is
+     * simply itself.
+     */
+    readonly substituteAbsentType: (type: ts.Type) => ts.Type;
+    /** Declared or undeclared host-absent globals answered, for measurement. */
+    readonly absentCount: number;
+    /**
+     * The ambient declarations this census denied.
+     *
+     * Exposed because a cell's STORAGE CLASS is decided in two places -- the
+     * binding producer, and the frontend's own ambient-value census that the
+     * projection reads (`FrontendResult.externalBindings`) -- and both have to
+     * reach the same answer. A declaration that stayed external in one of them
+     * emits `extern gea::Undefined VideoFrame;`: a symbol nothing defines, for a
+     * value this compiler has just concluded is not there.
+     */
+    readonly declarations: ReadonlySet<ts.Declaration>;
+}
+/** A census that answers for nothing, for a compilation whose hosts state no absent name. */
+export declare const emptyAbsentGlobalCensus: AbsentGlobalCensus;
+/** Whether a declaration is the PLATFORM's rather than the program's -- see `platformDeclarationTest`. */
+type PlatformTest = (node: ts.Declaration) => boolean;
+/**
+ * The test for "this declaration is the platform's, not the program's".
+ *
+ * `hasNoDefaultLib` alone is too narrow. `@types/webxr` is a DefinitelyTyped
+ * package describing a browser API; it stands in exactly the relation to the
+ * program that `lib.dom.d.ts` does -- the program installed it, did not write
+ * it, and holds no opinion about whether the platform implements it. Restricted
+ * to `hasNoDefaultLib`, a host could deny `HTMLImageElement` and not
+ * `XRWebGLLayer`, which is an accident of which file TypeScript happens to ship
+ * rather than a distinction about authority. It cost the three.js app 81 unmet
+ * obligations for `XRWebGLLayer@1`/`XRWebGLBinding@1` -- names three.js itself
+ * guards with `typeof XRWebGLBinding !== 'undefined'`.
+ *
+ * What the original narrowness protected is still protected: a PROGRAM's own
+ * `declare var VideoFrame` is an assertion about its own environment, and
+ * denying that would be a larger claim than a host may make. That is why the
+ * widening is `isDeclarationFile` AND `isSourceFileFromExternalLibrary` -- the
+ * program's own sources, including its own `.d.ts` files, are untouched, and
+ * `isSourceFileFromExternalLibrary` is the program's own answer rather than a
+ * path guess.
+ */
+export declare const platformDeclarationTest: (program: ts.Program) => PlatformTest;
+/**
+ * The census for one program.
+ *
+ * Resolve the name's symbol before applying a host fact. A program's own
+ * `const ImageData = ...`, or an import bound to that name, stays untouched.
+ * Platform declarations and references with no declaration can both receive
+ * the host's explicit absence fact. Missing declarations alone never establish
+ * absence: the installed host must have listed the name independently.
+ */
+export declare const censusAbsentGlobals: (checker: ts.TypeChecker, files: readonly ts.SourceFile[], absent: ReadonlySet<string>, platform: PlatformTest, namespacePaths: NamespacePathCensus) => AbsentGlobalCensus;
+export {};