@geastack/compiler 1.0.15

package/dist/semantics/package-sources.js

@@ -0,0 +1,365 @@
+import ts from 'typescript';
+import { dirname, resolve, relative } from 'node:path';
+const recordOf = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+// TypeScript reports paths with forward slashes on every platform, while
+// node:path joins with a backslash on Windows. Appending `sep` therefore made
+// every containment test fail there: the `sourceRoot` walk in readRecord climbed
+// to the drive root, where `dirname('C:/')` stops changing, and the loop spun
+// forever — a Windows build never finished, it only looked slow. Compare the two
+// paths on a single separator instead.
+const separators = /[\\/]+/g;
+const sameShape = (value) => value.replace(separators, '/').replace(/\/$/, '');
+const inside = (file, directory) => {
+    const target = sameShape(file);
+    const root = sameShape(directory);
+    return target === root || target.startsWith(`${root}/`);
+};
+const typedFile = (file) => /\.(?:ts|tsx|mts|cts)$/.test(file) && !/\.d\.(?:ts|mts|cts)$/.test(file);
+/**
+ * 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 const createPackageSourceHost = (host, packages = []) => {
+    const parseHost = host;
+    const readDirectory = parseHost.readDirectory?.bind(host) ?? ts.sys.readDirectory;
+    const records = new Map();
+    const packageOf = (file) => {
+        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;
+        }
+    };
+    const readRecord = (root) => {
+        if (records.has(root))
+            return records.get(root);
+        // Install the sentinel before parsing configs, whose extends can re-enter lookup.
+        records.set(root, undefined);
+        const text = host.readFile(`${root}/package.json`);
+        if (text === undefined)
+            return undefined;
+        let manifest;
+        try {
+            manifest = recordOf(JSON.parse(text));
+        }
+        catch {
+            return undefined;
+        }
+        if (!manifest)
+            return undefined;
+        const mappings = new Map();
+        const roots = [];
+        const patterns = [];
+        const inputs = [];
+        const add = (output, source) => {
+            const from = resolve(root, output);
+            const to = resolve(root, source);
+            if (!inside(from, root) || !inside(to, root) || !typedFile(to))
+                return;
+            if (from.includes('*') && to.includes('*'))
+                patterns.push([from, to]);
+            else if (host.fileExists(to))
+                mappings.set(from, to);
+        };
+        const sourceConditions = (value) => {
+            if (Array.isArray(value)) {
+                value.forEach(sourceConditions);
+                return;
+            }
+            const object = recordOf(value);
+            if (!object)
+                return;
+            const sources = Object.entries(object).filter(([key, entry]) => (key === 'source' || key.endsWith('/source')) && typeof entry === 'string');
+            if (sources.length === 1) {
+                const source = sources[0]?.[1];
+                if (typeof source === 'string')
+                    for (const [key, output] of Object.entries(object)) {
+                        if (key !== 'types' && typeof output === 'string')
+                            add(output, source);
+                    }
+            }
+            Object.values(object).forEach(sourceConditions);
+        };
+        sourceConditions(manifest.exports);
+        if (typeof manifest.source === 'string') {
+            for (const field of ['main', 'module'])
+                if (typeof manifest[field] === 'string')
+                    add(manifest[field], manifest.source);
+        }
+        for (const name of ['tsconfig.json', 'tsconfig.build.json']) {
+            const file = resolve(root, name);
+            if (!host.fileExists(file))
+                continue;
+            const config = ts.readConfigFile(file, host.readFile);
+            if (config.error)
+                continue;
+            const parsed = ts.parseJsonConfigFileContent(config.config, {
+                useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+                fileExists: host.fileExists,
+                readFile: host.readFile,
+                readDirectory
+            }, root);
+            let sourceRoot = parsed.options.rootDir;
+            const configInputs = parsed.fileNames.filter(typedFile);
+            inputs.push(...configInputs);
+            if (!sourceRoot && configInputs.length > 0) {
+                sourceRoot = dirname(configInputs[0]);
+                // Stop at the filesystem root even when an input is genuinely outside it:
+                // dirname() is idempotent there, so without this the walk cannot end.
+                for (const input of configInputs)
+                    while (!inside(input, sourceRoot)) {
+                        const parent = dirname(sourceRoot);
+                        if (parent === sourceRoot)
+                            break;
+                        sourceRoot = parent;
+                    }
+            }
+            if (sourceRoot && parsed.options.outDir)
+                roots.push([parsed.options.outDir, sourceRoot]);
+        }
+        // Packages commonly emit declarations and JavaScript into sibling trees:
+        // `src/index.ts` -> `dist/types/index.d.ts` and `dist/index.js`. The
+        // tsconfig proves the first relationship, while the exports entry proves
+        // that both outputs implement the same public subpath. Carry that proof
+        // across to the runtime target so a source checkout does not need to keep
+        // generated JavaScript or add geatsc-specific metadata.
+        const sourceFromDeclaredOutput = (output) => {
+            const absolute = resolve(root, output);
+            for (const [outDir, sourceDir] of roots) {
+                if (!inside(absolute, outDir))
+                    continue;
+                const base = resolve(sourceDir, relative(outDir, absolute)).replace(/\.d\.(?:ts|mts|cts)$/, '');
+                if (base.includes('*'))
+                    return `${base}.ts`;
+                const candidates = ['.ts', '.tsx', '.mts', '.cts'].map((extension) => `${base}${extension}`).filter(host.fileExists);
+                if (candidates.length === 1)
+                    return candidates[0];
+                const suffix = relative(outDir, absolute).replace(/\.d\.(?:ts|mts|cts)$/, '');
+                const suffixCandidates = inputs.filter((input) => {
+                    const source = relative(root, input).replace(/\.(?:ts|tsx|mts|cts)$/, '');
+                    return source === suffix || source.endsWith(`/${suffix}`);
+                });
+                if (suffixCandidates.length === 1)
+                    return suffixCandidates[0];
+            }
+            return undefined;
+        };
+        const inferRuntimeSources = (value) => {
+            if (Array.isArray(value)) {
+                value.forEach(inferRuntimeSources);
+                return;
+            }
+            const object = recordOf(value);
+            if (!object)
+                return;
+            const declared = typeof object.types === 'string' ? sourceFromDeclaredOutput(object.types) : undefined;
+            if (declared)
+                for (const [condition, output] of Object.entries(object))
+                    if (condition !== 'types' && typeof output === 'string' && !/\.d\.(?:ts|mts|cts)$/.test(output))
+                        add(output, declared);
+            Object.values(object).forEach(inferRuntimeSources);
+        };
+        inferRuntimeSources(manifest.exports);
+        // Static Rollup input/output declarations are data. Never execute build configs
+        // or plugins to discover a file; dynamic configs retain normal resolution.
+        for (const extension of ['js', 'mjs', 'cjs', 'ts']) {
+            const file = resolve(root, `rollup.config.${extension}`);
+            const code = host.readFile(file);
+            if (code === undefined)
+                continue;
+            const ast = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true);
+            const constants = new Map();
+            for (const statement of ast.statements)
+                if (ts.isVariableStatement(statement)) {
+                    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+                        continue;
+                    for (const declaration of statement.declarationList.declarations) {
+                        if (ts.isIdentifier(declaration.name) && declaration.initializer)
+                            constants.set(declaration.name.text, declaration.initializer);
+                    }
+                }
+            const valueOf = (node, seen = new Set()) => {
+                if (!ts.isIdentifier(node) || seen.has(node.text))
+                    return node;
+                const value = constants.get(node.text);
+                if (!value)
+                    return node;
+                seen.add(node.text);
+                return valueOf(value, seen);
+            };
+            const property = (node, name) => {
+                for (const item of node.properties) {
+                    if (!item.name || (!ts.isIdentifier(item.name) && !ts.isStringLiteral(item.name)) || item.name.text !== name)
+                        continue;
+                    if (ts.isPropertyAssignment(item))
+                        return valueOf(item.initializer);
+                    if (ts.isShorthandPropertyAssignment(item))
+                        return valueOf(item.name);
+                }
+                return undefined;
+            };
+            const visit = (expression) => {
+                const node = valueOf(expression);
+                if (ts.isArrayLiteralExpression(node)) {
+                    node.elements.forEach(visit);
+                    return;
+                }
+                if (!ts.isObjectLiteralExpression(node))
+                    return;
+                const input = property(node, 'input');
+                const output = property(node, 'output');
+                if (!input || !ts.isStringLiteralLike(input) || !output)
+                    return;
+                const outputs = ts.isArrayLiteralExpression(output) ? output.elements : [output];
+                for (const item of outputs) {
+                    const target = valueOf(item);
+                    if (!ts.isObjectLiteralExpression(target))
+                        continue;
+                    const destination = property(target, 'file');
+                    if (destination && ts.isStringLiteralLike(destination))
+                        add(destination.text, input.text);
+                }
+            };
+            for (const statement of ast.statements)
+                if (ts.isExportAssignment(statement))
+                    visit(statement.expression);
+        }
+        // esbuild's explicit outbase/outdir pair identifies preserved module paths.
+        // Inspect only scripts named by package metadata, never execute their code.
+        const buildFiles = new Set();
+        for (const [name, script] of Object.entries(recordOf(manifest.scripts) ?? {})) {
+            if (!/^(?:build|compile)(?::|$)/.test(name) || typeof script !== 'string')
+                continue;
+            for (const token of script.matchAll(/(?:^|\s)([\w./-]+\.(?:mjs|cjs|js|ts))(?=\s|$)/g))
+                buildFiles.add(resolve(root, token[1]));
+        }
+        for (const file of buildFiles) {
+            if (!inside(file, root))
+                continue;
+            const code = host.readFile(file);
+            if (code === undefined)
+                continue;
+            const ast = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true);
+            const visit = (node) => {
+                if (ts.isObjectLiteralExpression(node)) {
+                    const fields = new Map();
+                    for (const property of node.properties) {
+                        if (ts.isPropertyAssignment(property) &&
+                            (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+                            ts.isStringLiteralLike(property.initializer)) {
+                            fields.set(property.name.text, property.initializer.text);
+                        }
+                    }
+                    const source = fields.get('outbase'), output = fields.get('outdir');
+                    if (source && output && inside(resolve(root, source), root) && inside(resolve(root, output), root))
+                        roots.push([resolve(root, output), resolve(root, source)]);
+                }
+                ts.forEachChild(node, visit);
+            };
+            visit(ast);
+        }
+        // A literal build-script move relocates already identified outputs without
+        // evaluating the script. It cannot create a new source association.
+        for (const script of Object.values(recordOf(manifest.scripts) ?? {})) {
+            if (typeof script !== 'string')
+                continue;
+            for (const match of script.matchAll(/(?:^|&&|;)\s*mv\s+([\w./-]+)\/\*\.js\s+([\w./-]+)(?=\s*(?:&&|;|$))/g)) {
+                const from = resolve(root, match[1]);
+                const to = resolve(root, match[2]);
+                for (const [output, input] of [...mappings])
+                    if (dirname(output) === from)
+                        add(resolve(to, relative(from, output)), input);
+            }
+        }
+        const result = { manifest, mappings, patterns, roots, inputs };
+        records.set(root, result);
+        return result;
+    };
+    const entries = packages.map((entry) => ({ ...entry, root: resolve(entry.root), name: readRecord(resolve(entry.root))?.manifest.name }));
+    const aliases = entries
+        .filter((entry) => typeof entry.name === 'string')
+        .map((entry) => ({
+        ...entry,
+        prefix: resolve(entry.root, 'node_modules', String(entry.name))
+    }));
+    const unalias = (file) => {
+        const absolute = resolve(file);
+        const alias = aliases.find((entry) => inside(absolute, entry.prefix));
+        if (alias)
+            return resolve(alias.root, relative(alias.prefix, absolute));
+        const origin = entries
+            .filter((entry) => entry.origin && inside(absolute, resolve(entry.origin)))
+            .sort((left, right) => right.origin.length - left.origin.length)[0];
+        return origin?.origin ? resolve(origin.root, relative(resolve(origin.origin), absolute)) : absolute;
+    };
+    const sourceOf = (file) => {
+        const absolute = unalias(file);
+        const root = packageOf(absolute);
+        const record = root ? readRecord(root) : undefined;
+        const stated = record?.mappings.get(absolute);
+        if (stated)
+            return stated;
+        for (const [output, input] of record?.patterns ?? []) {
+            const [prefix, suffix] = output.split('*');
+            if (!prefix || suffix === undefined || !absolute.startsWith(prefix) || !absolute.endsWith(suffix))
+                continue;
+            const candidate = input.replace('*', absolute.slice(prefix.length, absolute.length - suffix.length));
+            if (inside(candidate, root) && host.fileExists(candidate))
+                return candidate;
+        }
+        for (const [output, source] of record?.roots ?? []) {
+            if (!inside(absolute, output))
+                continue;
+            const base = resolve(source, relative(output, absolute)).replace(/(?:\.d)?\.(?:js|jsx|mjs|cjs|ts|mts|cts)$/, '');
+            const candidates = ['.ts', '.tsx', '.mts', '.cts'].map((extension) => `${base}${extension}`).filter(host.fileExists);
+            if (candidates.length === 1 && candidates[0])
+                return candidates[0];
+        }
+        return host.fileExists(absolute) ? absolute : resolve(file);
+    };
+    const view = {
+        ...host,
+        fileExists: (file) => host.fileExists(sourceOf(file)),
+        readFile: (file) => host.readFile(sourceOf(file)),
+        directoryExists: (directory) => {
+            if (aliases.some((entry) => inside(entry.prefix, resolve(directory))))
+                return true;
+            const dir = unalias(directory);
+            if (host.directoryExists?.(dir))
+                return true;
+            const root = packageOf(`${dir}/__module__.ts`);
+            const record = root ? readRecord(root) : undefined;
+            if ([...(record?.mappings.keys() ?? [])].some((file) => inside(file, dir)))
+                return true;
+            if (record?.patterns.some(([pattern]) => inside(pattern, dir) || dir.startsWith(pattern.split('*')[0])))
+                return true;
+            return (record?.roots ?? []).some(([output, source]) => inside(dir, output) && host.directoryExists?.(resolve(source, relative(output, dir))));
+        },
+        realpath: (file) => {
+            const source = sourceOf(file);
+            return host.realpath?.(source) ?? source;
+        }
+    };
+    return {
+        host: view,
+        sourceOf,
+        containingFile: (specifier, containingFile) => {
+            const own = entries.find((entry) => !entry.origin && typeof entry.name === 'string' && (specifier === entry.name || specifier.startsWith(`${entry.name}/`)));
+            if (own)
+                return resolve(own.root, '__geatsc_entry__.ts');
+            if (!specifier.startsWith('.') && !specifier.startsWith('/')) {
+                const source = entries
+                    .filter((entry) => entry.origin && inside(resolve(containingFile), entry.root))
+                    .sort((left, right) => right.root.length - left.root.length)[0];
+                if (source?.origin)
+                    return resolve(source.origin, relative(source.root, containingFile));
+            }
+            return containingFile;
+        }
+    };
+};

package/dist/semantics/program.d.ts

@@ -0,0 +1,151 @@
+import type { PackageSource } from './package-sources.js';
+import ts from 'typescript';
+import type { CommonJsWrapperDeclaration } from '../plugins/model.js';
+import { type HostMethodBindingTable } from './host-methods.js';
+import { type DiagnosticSourcePreparationAudit } from './diagnostic-source-preparation.js';
+/**
+ * The TypeScript program host.
+ *
+ * This is the only place the compiler opens a file. Everything downstream reads
+ * the sealed semantic graph, so a later layer physically cannot reach back to
+ * the AST to answer a question the frontend already answered differently.
+ */
+export interface ProgramInput {
+    /** Package checkouts prepared by the project loader; the compiler discovers their implementation entries. */
+    readonly packageSources?: readonly PackageSource[];
+    readonly dynamicFallback?: boolean;
+    /** Module specifiers implemented by an installed native host, including explicit package/* claims. */
+    readonly declarationModules?: ReadonlySet<string>;
+    readonly rootFileNames: readonly string[];
+    readonly options: ts.CompilerOptions;
+    /**
+     * File text this program uses in place of what is on disk, by absolute path.
+     *
+     * A build pipeline does not always hand a compiler the files a user wrote.
+     * The gea vite pipeline captures each module at a chosen point in its own
+     * transform chain and compiles THOSE, so the text for a path can differ from
+     * the file at that path -- and one module (`@gea-virtual/...`) has no file at
+     * all. Both are the same fact: the caller, not the filesystem, is the
+     * authority on a module's text. The paths stay the real ones because import
+     * resolution is done against them.
+     */
+    readonly sourceOverlay?: ReadonlyMap<string, string>;
+    /**
+     * How an importing file's own specifiers resolve, when the caller knows and
+     * ordinary resolution cannot. A bundler's virtual module (`virtual:...`) and
+     * an alias it invented have no on-disk meaning; the build that created them
+     * is the only authority on where they point.
+     */
+    readonly moduleResolution?: ReadonlyMap<string, ReadonlyMap<string, string>>;
+    /** Exact host-owned declarations whose static calls are CommonJS loaders. */
+    readonly commonJsGlobals?: ReadonlyMap<string, CommonJsWrapperDeclaration>;
+    /** Host-owned method declarations used to authenticate builtin record lookups. */
+    readonly hostMethodBindings?: HostMethodBindingTable;
+    /** Accepted runtime lookup spellings, mapped to canonical builtin names. */
+    readonly commonJsBuiltinModules?: ReadonlyMap<string, string>;
+    /** Real implementation sources keyed by canonical builtin registry name. */
+    readonly commonJsBuiltinModuleSources?: ReadonlyMap<string, string>;
+    /**
+     * The project file whose options and file set define this program, or `null`
+     * to compile the root files under `options` alone.
+     *
+     * A program is not just its entry points. A project's `include` pulls in the
+     * ambient declarations that give a wildcard import (`import './App.css'`) a
+     * module to resolve to, and its `paths` decide what a specifier means at all.
+     * Compiling the entry points under this compiler's own defaults compiles a
+     * *different program* than the one the application declares, and every
+     * difference surfaces as a phantom defect in the application.
+     */
+    /**
+     * Whether the CALLER has stated the module set (it compiled a module graph),
+     * so the project must not add modules of its own.
+     *
+     * A project's `include` and a module graph answer two different questions. A
+     * glob says what a typechecker should be willing to look at; a graph says
+     * what this application actually is. On the module-graph path the staged
+     * project is written beside the entry and its `include` is a wildcard, so it
+     * sweeps up every sibling left in the staging directory -- files the bundler
+     * shook out, and untransformed originals whose specifiers only ever meant
+     * something to the bundler. Compiled as roots, their unresolved imports are
+     * reported as defects of an application that does not contain them.
+     *
+     * The project still contributes everything it is the authority on: its
+     * options, its `paths`, and its ambient DECLARATIONS -- which is what the
+     * comment above is about, and what a wildcard import still needs. Only its
+     * implementation files are dropped, because the graph already named those.
+     */
+    readonly statedModuleSet?: boolean;
+    /**
+     * The caller guarantees that this program contains every classic script
+     * that can execute in its lexical realm, including any evaluated source.
+     * Absent, another script may read or write top-level lexical bindings.
+     * This does not close global-object properties, host effects, or objects
+     * held by lexical bindings. It is independent of ESM module completeness
+     * and C++ symbol isolation, neither of which supplies this guarantee.
+     */
+    readonly closedScriptScope?: boolean;
+    readonly projectFileName?: string | null;
+    /**
+     * Rewrites a plugin performs on a file's text before this program parses it
+     * (`PluginInstance.transformSource`), applied in installation order.
+     *
+     * The only place a transform can run and still change what the CHECKER sees,
+     * which is the whole reason the hook exists: a library whose meaning the type
+     * system cannot express -- AppKit's JSX, whose elements the language types as
+     * `JSX.Element` and whose attributes it does not check at all -- has to
+     * become ordinary TypeScript before checking, not after. Empty is the normal
+     * case and costs nothing.
+     */
+    readonly sourceTransforms?: readonly ((input: {
+        readonly fileName: string;
+        readonly text: string;
+        readonly declarationFileName?: string;
+    }) => string | null)[];
+}
+export interface CompiledProgram {
+    readonly program: ts.Program;
+    readonly checker: ts.TypeChecker;
+    /**
+     * The program host's runtime-module answer for a literal specifier.
+     *
+     * CommonJS `require("...")` is not a TypeScript module-specifier node, so
+     * its argument has no checker module symbol.  This keeps resolution on the
+     * configured program host, including overlays, package-source rewrites, and
+     * caller-stated module graphs, instead of letting a producer re-resolve it.
+     */
+    readonly runtimeModuleTargetOf: (specifier: string, containingFile: string, mode: 'import' | 'require') => string | null;
+    /** The Program's canonical source-file object for a resolved path. */
+    readonly sourceFileOf: (fileName: string) => ts.SourceFile | null;
+    /** Source files reached only through authenticated static CommonJS require edges. */
+    readonly commonJsSourceFiles: readonly ts.SourceFile[];
+    /** The files the compiler is responsible for, excluding ambient declarations. */
+    readonly sourceFiles: readonly ts.SourceFile[];
+    /**
+     * The files the caller asked to compile, as this program's own source files.
+     *
+     * A program is not just its entry points -- `ProgramInput.projectFileName`
+     * says why -- but the difference between the two is exactly what
+     * `censusReachability` (normalize/reachability.ts) needs, and only this file
+     * can state it: a root arrives as whatever path the caller wrote, and
+     * turning one into a `ts.SourceFile` is module resolution, which is this
+     * file's job and no later layer's. Empty means the roots could not be
+     * resolved, and reachability then prunes nothing.
+     */
+    readonly entryFiles: readonly ts.SourceFile[];
+    /** Syntactic and semantic errors TypeScript itself reports. */
+    readonly diagnostics: readonly ts.Diagnostic[];
+    /** Exact stale package-source directives blanked before the final checker pass. */
+    readonly sourcePreparations: readonly DiagnosticSourcePreparationAudit[];
+}
+export declare const defaultCompilerOptions: ts.CompilerOptions;
+/**
+ * The nearest project file at or above a directory, or `null`.
+ *
+ * This walks the filesystem, which looks like the source-shaped authority the
+ * architecture forbids -- it is not. The forbidden thing is deciding a value's
+ * *semantics* from a path. Finding the project that declares a program is how
+ * every TypeScript toolchain establishes what the program even is, and the
+ * answer feeds `ts.parseJsonConfigFileContent`, never a semantic decision.
+ */
+export declare const findProjectFile: (fromDirectory: string) => string | null;
+export declare const createProgram: (input: ProgramInput) => CompiledProgram;