ushman-equiv 0.4.0

package/dist/analysis-context.js

@@ -0,0 +1,708 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import traverseImport from '@babel/traverse';
+import { isCallExpression, isClassDeclaration, isExportAllDeclaration, isExportDefaultDeclaration, isExportNamedDeclaration, isExportSpecifier, isFunctionDeclaration, isIdentifier, isImportDeclaration, isImportDefaultSpecifier, isImportNamespaceSpecifier, isImportSpecifier, isRestElement, isStringLiteral, } from '@babel/types';
+import { asNode, isArrayPatternNode, isAssignmentPatternNode, isClassDeclarationNode, isFunctionDeclarationNode, isIdentifierNode, isObjectPatternNode, isObjectPropertyNode, isVariableDeclarationNode, isVariableDeclaratorNode, } from "./ast-guards.js";
+import { compareStrings } from "./shared.js";
+import { assertV4Workspace, chunk, collectSourceFiles, createFilterMatcher, DEFAULT_MAX_CONCURRENCY, discoverEntrypoint, displayPath, importMapMatchesSpecifier, isBareSpecifier, loadImportMap, normalizeImportSpecifier, parseSourceFile, resolveRelativeSpecifier, } from "./workspace.js";
+const resolveTraverse = () => {
+    const traverseNamespace = traverseImport;
+    if (typeof traverseImport === 'function') {
+        return traverseImport;
+    }
+    if (traverseNamespace && typeof traverseNamespace === 'object' && typeof traverseNamespace.default === 'function') {
+        return traverseNamespace.default;
+    }
+    throw new TypeError('Unable to resolve @babel/traverse default export.');
+};
+const traverse = resolveTraverse();
+const analysisTestHooksStorage = new AsyncLocalStorage();
+export const withAnalysisContextTestHooks = async ({ hooks, run, }) => await analysisTestHooksStorage.run(hooks, run);
+const getBareUsage = (usages, specifier) => {
+    const current = usages.get(specifier) ??
+        {
+            defaultImported: false,
+            namedImports: new Set(),
+            namespaceImported: false,
+        };
+    usages.set(specifier, current);
+    return current;
+};
+const addNamedImport = (usage, importedName) => {
+    if (importedName !== 'default') {
+        usage.namedImports.add(importedName);
+    }
+};
+const addPendingImport = (pendingImports, importerPath, specifier) => {
+    pendingImports.push({
+        importerPath,
+        specifier,
+    });
+};
+const readModuleExportName = (value) => {
+    const node = asNode(value);
+    if (!node) {
+        return null;
+    }
+    if (isIdentifierNode(node)) {
+        return node.name;
+    }
+    if (isStringLiteral(node)) {
+        return node.value;
+    }
+    return null;
+};
+const recordNamespaceMemberUsage = (bareUsages, namespaceAliases, node) => {
+    if (!isIdentifier(node.object)) {
+        return;
+    }
+    const specifier = namespaceAliases.get(node.object.name);
+    if (!specifier) {
+        return;
+    }
+    const usage = getBareUsage(bareUsages, specifier);
+    if (!node.computed && isIdentifier(node.property)) {
+        usage.namedImports.add(node.property.name);
+        return;
+    }
+    if (isStringLiteral(node.property)) {
+        usage.namedImports.add(node.property.value);
+    }
+};
+const collectNamespaceObjectPatternKeys = (pattern) => {
+    const node = asNode(pattern);
+    if (!isObjectPatternNode(node)) {
+        return [];
+    }
+    const names = new Set();
+    for (const property of node.properties) {
+        if (!isObjectPropertyNode(property)) {
+            continue;
+        }
+        const keyName = readModuleExportName(property.key);
+        if (keyName) {
+            names.add(keyName);
+        }
+    }
+    return [...names];
+};
+const recordNamespaceDestructureUsage = ({ bareUsages, id, init, namespaceAliases, }) => {
+    if (!isIdentifierNode(init)) {
+        return;
+    }
+    const specifier = namespaceAliases.get(init.name);
+    if (!specifier) {
+        return;
+    }
+    const usage = getBareUsage(bareUsages, specifier);
+    for (const name of collectNamespaceObjectPatternKeys(id)) {
+        usage.namedImports.add(name);
+    }
+};
+const recordImportDeclaration = ({ bareUsages, namespaceAliases, pendingImports, source, sourceFile, specifiers, }) => {
+    addPendingImport(pendingImports, sourceFile, source);
+    if (!isBareSpecifier(source)) {
+        return;
+    }
+    const usage = getBareUsage(bareUsages, source);
+    for (const specifier of specifiers) {
+        if (isImportDefaultSpecifier(specifier)) {
+            usage.defaultImported = true;
+            continue;
+        }
+        if (isImportNamespaceSpecifier(specifier)) {
+            usage.namespaceImported = true;
+            namespaceAliases.set(specifier.local.name, source);
+            continue;
+        }
+        if (isImportSpecifier(specifier)) {
+            addNamedImport(usage, isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value);
+        }
+    }
+};
+const recordExportNamedImport = ({ bareUsages, pendingImports, source, sourceFile, specifiers, }) => {
+    addPendingImport(pendingImports, sourceFile, source);
+    if (!isBareSpecifier(source)) {
+        return;
+    }
+    const usage = getBareUsage(bareUsages, source);
+    for (const specifier of specifiers) {
+        if (!isExportSpecifier(specifier)) {
+            continue;
+        }
+        const importedName = readModuleExportName(specifier.local);
+        if (!importedName) {
+            continue;
+        }
+        addNamedImport(usage, importedName);
+    }
+};
+const scanImportUsages = ({ ast, bareUsages, pendingImports, relativePath, sourceFile, warnings, }) => {
+    const namespaceAliases = new Map();
+    traverse(ast, {
+        CallExpression(path) {
+            if (!isCallExpression(path.node) || path.node.callee.type !== 'Import') {
+                return;
+            }
+            const [argument] = path.node.arguments;
+            if (isStringLiteral(argument)) {
+                addPendingImport(pendingImports, sourceFile, argument.value);
+                return;
+            }
+            warnings.push({
+                message: 'Skipped non-literal dynamic import.',
+                path: relativePath,
+            });
+        },
+        ExportAllDeclaration(path) {
+            const source = path.node.source.value;
+            addPendingImport(pendingImports, sourceFile, source);
+        },
+        ExportNamedDeclaration(path) {
+            const source = path.node.source?.value;
+            if (source) {
+                recordExportNamedImport({
+                    bareUsages,
+                    pendingImports,
+                    source,
+                    sourceFile,
+                    specifiers: path.node.specifiers,
+                });
+            }
+        },
+        ImportDeclaration(path) {
+            recordImportDeclaration({
+                bareUsages,
+                namespaceAliases,
+                pendingImports,
+                source: path.node.source.value,
+                sourceFile,
+                specifiers: path.node.specifiers,
+            });
+        },
+        MemberExpression(path) {
+            recordNamespaceMemberUsage(bareUsages, namespaceAliases, path.node);
+        },
+        OptionalMemberExpression(path) {
+            recordNamespaceMemberUsage(bareUsages, namespaceAliases, path.node);
+        },
+        VariableDeclarator(path) {
+            if (!isVariableDeclaratorNode(path.node)) {
+                return;
+            }
+            recordNamespaceDestructureUsage({
+                bareUsages,
+                id: path.node.id,
+                init: path.node.init,
+                namespaceAliases,
+            });
+        },
+    });
+};
+const collectArrayPatternNames = (pattern, names) => {
+    const node = asNode(pattern);
+    if (!isArrayPatternNode(node)) {
+        return false;
+    }
+    for (const element of node.elements) {
+        if (!element) {
+            continue;
+        }
+        collectPatternNames(element, names);
+    }
+    return true;
+};
+const collectObjectPatternNames = (pattern, names) => {
+    const node = asNode(pattern);
+    if (!isObjectPatternNode(node)) {
+        return false;
+    }
+    for (const property of node.properties) {
+        if (isRestElement(property)) {
+            collectPatternNames(property.argument, names);
+            continue;
+        }
+        if (isObjectPropertyNode(property)) {
+            collectPatternNames(property.value, names);
+        }
+    }
+    return true;
+};
+const collectPatternNames = (pattern, names) => {
+    const node = asNode(pattern);
+    if (!node) {
+        return;
+    }
+    if (isIdentifierNode(node)) {
+        names.add(node.name);
+        return;
+    }
+    if (isAssignmentPatternNode(node)) {
+        collectPatternNames(node.left, names);
+        return;
+    }
+    if (collectArrayPatternNames(node, names) || collectObjectPatternNames(node, names)) {
+        return;
+    }
+    if (isRestElement(node)) {
+        collectPatternNames(node.argument, names);
+    }
+};
+const addDeclaration = (declarations, exportedNames, kind, name, markExported = false) => {
+    const existingKind = declarations.get(name);
+    if (!existingKind || existingKind === 'export') {
+        declarations.set(name, kind);
+    }
+    if (markExported || kind === 'export') {
+        exportedNames.add(name);
+    }
+};
+const visitExportNamedStatement = ({ declarations, exportedNames, statement, }) => {
+    if (statement.declaration) {
+        for (const name of collectDeclaredNames(statement.declaration)) {
+            exportedNames.add(name);
+        }
+        visitTopLevelStatement({
+            declarations,
+            exportedNames,
+            statement: statement.declaration,
+        });
+    }
+    for (const specifier of statement.specifiers) {
+        if (!isExportSpecifier(specifier)) {
+            continue;
+        }
+        const exportedName = readModuleExportName(specifier.exported);
+        if (exportedName) {
+            addDeclaration(declarations, exportedNames, 'export', exportedName, true);
+        }
+    }
+};
+const visitExportAllStatement = ({ declarations, exportedNames, statement, }) => {
+    if (!isExportAllDeclaration(statement)) {
+        return false;
+    }
+    const exportedName = readModuleExportName(statement.exported);
+    if (exportedName) {
+        addDeclaration(declarations, exportedNames, 'export', exportedName, true);
+    }
+    return true;
+};
+const visitExportDefaultStatement = ({ declarations, exportedNames, statement, }) => {
+    if (!isExportDefaultDeclaration(statement)) {
+        return false;
+    }
+    addDeclaration(declarations, exportedNames, 'export', 'default', true);
+    if (!isFunctionDeclaration(statement.declaration) && !isClassDeclaration(statement.declaration)) {
+        return true;
+    }
+    const declaration = statement.declaration;
+    visitTopLevelStatement({
+        declarations,
+        exportedNames,
+        statement: declaration,
+    });
+    return true;
+};
+const collectDeclaredNames = (statement) => {
+    const node = asNode(statement);
+    if (!node) {
+        return [];
+    }
+    if (isFunctionDeclarationNode(node) && node.id) {
+        return [node.id.name];
+    }
+    if (isClassDeclarationNode(node) && node.id) {
+        return [node.id.name];
+    }
+    if (!isVariableDeclarationNode(node)) {
+        return [];
+    }
+    const names = new Set();
+    for (const declaration of node.declarations) {
+        collectPatternNames(declaration.id, names);
+    }
+    return [...names];
+};
+const recordTopLevelDeclaration = ({ declarations, exportedNames, statement, }) => {
+    if (isFunctionDeclarationNode(statement) && statement.id) {
+        addDeclaration(declarations, exportedNames, 'function', statement.id.name);
+        return true;
+    }
+    if (isClassDeclarationNode(statement) && statement.id) {
+        addDeclaration(declarations, exportedNames, 'class', statement.id.name);
+        return true;
+    }
+    if (!isVariableDeclarationNode(statement)) {
+        return false;
+    }
+    const names = collectDeclaredNames(statement);
+    for (const name of names) {
+        addDeclaration(declarations, exportedNames, statement.kind, name);
+    }
+    return true;
+};
+const visitTopLevelStatement = ({ declarations, exportedNames, statement, }) => {
+    if (isImportDeclaration(statement)) {
+        return;
+    }
+    if (recordTopLevelDeclaration({ declarations, exportedNames, statement })) {
+        return;
+    }
+    if (isExportNamedDeclaration(statement)) {
+        visitExportNamedStatement({
+            declarations,
+            exportedNames,
+            statement,
+        });
+        return;
+    }
+    if (visitExportAllStatement({
+        declarations,
+        exportedNames,
+        statement,
+    })) {
+        return;
+    }
+    visitExportDefaultStatement({
+        declarations,
+        exportedNames,
+        statement,
+    });
+};
+export const scanTopLevelDeclarations = (ast) => {
+    const declarations = new Map();
+    const exportedNames = new Set();
+    for (const statement of ast.program.body) {
+        visitTopLevelStatement({
+            declarations,
+            exportedNames,
+            statement,
+        });
+    }
+    return {
+        declarations,
+        exportedNames,
+    };
+};
+const toReadonlyBareUsages = (usages) => new Map([...usages.entries()].map(([specifier, usage]) => [
+    specifier,
+    {
+        defaultImported: usage.defaultImported,
+        namedImports: new Set(usage.namedImports),
+        namespaceImported: usage.namespaceImported,
+    },
+]));
+const mergeBareUsages = (target, source) => {
+    for (const [specifier, usage] of source.entries()) {
+        const current = getBareUsage(target, specifier);
+        current.defaultImported ||= usage.defaultImported;
+        current.namespaceImported ||= usage.namespaceImported;
+        for (const name of usage.namedImports) {
+            current.namedImports.add(name);
+        }
+    }
+};
+const resolveImportReferences = async ({ importMap, pendingImports, workspaceRoot, }) => {
+    const resolvedImports = [];
+    for (const pendingImportChunk of chunk(pendingImports, DEFAULT_MAX_CONCURRENCY)) {
+        const chunkResults = await Promise.all(pendingImportChunk.map(async (pendingImport) => {
+            const normalizedSpecifier = normalizeImportSpecifier(pendingImport.specifier);
+            if (isBareSpecifier(normalizedSpecifier)) {
+                const resolved = importMapMatchesSpecifier(importMap, normalizedSpecifier) !== null;
+                return {
+                    importerPath: pendingImport.importerPath,
+                    message: resolved ? undefined : `Missing bare specifier in importmap: ${normalizedSpecifier}`,
+                    resolved,
+                    specifier: normalizedSpecifier,
+                };
+            }
+            const resolvedPath = await resolveRelativeSpecifier({
+                importerPath: pendingImport.importerPath,
+                specifier: normalizedSpecifier,
+                workspaceRoot,
+            });
+            return {
+                importerPath: pendingImport.importerPath,
+                message: resolvedPath ? undefined : `Missing relative import: ${normalizedSpecifier}`,
+                resolved: resolvedPath !== null,
+                resolvedPath: resolvedPath ?? undefined,
+                specifier: normalizedSpecifier,
+            };
+        }));
+        resolvedImports.push(...chunkResults);
+    }
+    return resolvedImports;
+};
+const createParseFinding = (workspaceRoot, sourceFile, error) => ({
+    message: error instanceof Error ? error.message : String(error),
+    path: displayPath(workspaceRoot, sourceFile),
+});
+const createMissingRootWarnings = (missingRoots) => missingRoots.map((missingRoot) => ({
+    message: `Source root does not exist and was skipped: ${missingRoot}`,
+    path: missingRoot,
+}));
+const analyzeSourceFile = async ({ ast, sourceFile, workspaceRoot, }) => {
+    const warnings = [];
+    const pendingImports = [];
+    const bareUsages = new Map();
+    scanImportUsages({
+        ast,
+        bareUsages,
+        pendingImports,
+        relativePath: displayPath(workspaceRoot, sourceFile),
+        sourceFile,
+        warnings,
+    });
+    const symbolScan = scanTopLevelDeclarations(ast);
+    return {
+        bareUsages: toReadonlyBareUsages(bareUsages),
+        declarations: symbolScan.declarations,
+        exportedNames: symbolScan.exportedNames,
+        pendingImports,
+        warnings,
+    };
+};
+const makeFilterCacheKey = (filter) => filter ?? '__USHMAN_EQUIV_FILTER_ALL__';
+const recordSymbolIndexEntry = ({ byNameMutable, declarations, exportFiles, fileEntries, sourceFile, symbolEntry, }) => {
+    fileEntries.push(symbolEntry);
+    const existing = byNameMutable.get(symbolEntry.name) ?? [];
+    byNameMutable.set(symbolEntry.name, [...existing, symbolEntry]);
+    const existingKind = declarations.get(symbolEntry.name);
+    if (!existingKind || existingKind === 'export') {
+        declarations.set(symbolEntry.name, symbolEntry.kind);
+    }
+    if (symbolEntry.exported && !exportFiles.has(symbolEntry.name)) {
+        exportFiles.set(symbolEntry.name, sourceFile);
+    }
+};
+const sortSymbolIndexMaps = ({ byFileMutable, byNameMutable, }) => ({
+    byFile: new Map([...byFileMutable.entries()].sort(([left], [right]) => compareStrings(left, right))),
+    byName: new Map([...byNameMutable.entries()]
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([name, entries]) => [
+        name,
+        [...entries].sort((left, right) => compareStrings(left.filePath, right.filePath) || compareStrings(left.name, right.name)),
+    ])),
+});
+const buildSymbolIndex = async ({ getSourceAnalysis, missingRoots, sourceFiles, }) => {
+    const byFileMutable = new Map();
+    const byNameMutable = new Map();
+    const declarations = new Map();
+    const errors = [];
+    const exportFiles = new Map();
+    const warnings = createMissingRootWarnings(missingRoots);
+    for (const sourceFileChunk of chunk(sourceFiles, DEFAULT_MAX_CONCURRENCY)) {
+        const sourceFileAnalyses = await Promise.all(sourceFileChunk.map(async (sourceFile) => ({
+            analysis: await getSourceAnalysis(sourceFile),
+            sourceFile,
+        })));
+        for (const { analysis, sourceFile } of sourceFileAnalyses) {
+            if (analysis.parseFinding) {
+                errors.push(analysis.parseFinding);
+                continue;
+            }
+            const fileEntries = [];
+            for (const [name, kind] of analysis.declarations.entries()) {
+                recordSymbolIndexEntry({
+                    byNameMutable,
+                    declarations,
+                    exportFiles,
+                    fileEntries,
+                    sourceFile,
+                    symbolEntry: {
+                        exported: analysis.exportedNames.has(name),
+                        filePath: sourceFile,
+                        kind,
+                        name,
+                    },
+                });
+            }
+            if (fileEntries.length > 0) {
+                byFileMutable.set(sourceFile, fileEntries);
+            }
+        }
+    }
+    return {
+        ...sortSymbolIndexMaps({
+            byFileMutable,
+            byNameMutable,
+        }),
+        declarations,
+        errors,
+        exportFiles,
+        warnings,
+    };
+};
+/**
+ * Builds the shared per-workspace analysis context used by tier orchestration.
+ * The context owns entrypoint discovery, source walking, parse dedupe,
+ * import-graph filtering, and symbol-index reuse for a single workspace root.
+ */
+export const createAnalysisContext = async (options) => {
+    await assertV4Workspace(options.workspaceRoot);
+    const entrypointPath = await discoverEntrypoint({
+        entrypoint: options.entrypoint,
+        workspaceRoot: options.workspaceRoot,
+    });
+    const importMap = await loadImportMap(options.workspaceRoot);
+    const sourceCollection = await collectSourceFiles({
+        includeEntrypoint: entrypointPath,
+        srcRoots: options.srcRoots,
+        workspaceRoot: options.workspaceRoot,
+    });
+    const parsedSourceCache = new Map();
+    const sourceAnalysisCache = new Map();
+    const importGraphCache = new Map();
+    let symbolIndexPromise = null;
+    const getParsedSourceFile = (filePath) => {
+        const cached = parsedSourceCache.get(filePath);
+        if (cached) {
+            return cached;
+        }
+        const next = (async () => {
+            analysisTestHooksStorage.getStore()?.onParseSourceFile?.(filePath);
+            return parseSourceFile(filePath);
+        })();
+        parsedSourceCache.set(filePath, next);
+        void next.finally(() => {
+            if (parsedSourceCache.get(filePath) === next) {
+                parsedSourceCache.delete(filePath);
+            }
+        });
+        return next;
+    };
+    const getSourceAnalysis = (filePath) => {
+        const cached = sourceAnalysisCache.get(filePath);
+        if (cached) {
+            return cached;
+        }
+        const next = (async () => {
+            try {
+                const { ast } = await getParsedSourceFile(filePath);
+                return await analyzeSourceFile({
+                    ast,
+                    sourceFile: filePath,
+                    workspaceRoot: options.workspaceRoot,
+                });
+            }
+            catch (error) {
+                return {
+                    bareUsages: new Map(),
+                    declarations: new Map(),
+                    exportedNames: new Set(),
+                    parseFinding: createParseFinding(options.workspaceRoot, filePath, error),
+                    pendingImports: [],
+                    warnings: [],
+                };
+            }
+        })();
+        sourceAnalysisCache.set(filePath, next);
+        return next;
+    };
+    const aggregateImportGraph = async (filter) => {
+        const bareUsages = new Map();
+        const parseFindings = [];
+        const pendingImports = [];
+        const warnings = createMissingRootWarnings(sourceCollection.missingRoots);
+        const matcher = createFilterMatcher(filter);
+        const matchedFiles = sourceCollection.files.filter((sourceFile) => {
+            const relativePath = displayPath(options.workspaceRoot, sourceFile);
+            return sourceFile === entrypointPath || matcher(relativePath);
+        });
+        for (const sourceFileChunk of chunk(matchedFiles, DEFAULT_MAX_CONCURRENCY)) {
+            const analyses = await Promise.all(sourceFileChunk.map(async (sourceFile) => ({
+                analysis: await getSourceAnalysis(sourceFile),
+                sourceFile,
+            })));
+            for (const { analysis } of analyses) {
+                if (analysis.parseFinding) {
+                    parseFindings.push(analysis.parseFinding);
+                    continue;
+                }
+                mergeBareUsages(bareUsages, analysis.bareUsages);
+                pendingImports.push(...analysis.pendingImports);
+                warnings.push(...analysis.warnings);
+            }
+        }
+        return {
+            bareUsages: toReadonlyBareUsages(bareUsages),
+            parseFindings,
+            pendingImports,
+            warnings,
+        };
+    };
+    const getImportGraphAnalysis = (filter) => {
+        const cacheKey = makeFilterCacheKey(filter);
+        const cached = importGraphCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        const next = (async () => {
+            const aggregated = await aggregateImportGraph(filter);
+            const imports = await resolveImportReferences({
+                importMap,
+                pendingImports: aggregated.pendingImports,
+                workspaceRoot: options.workspaceRoot,
+            });
+            return {
+                bareUsages: aggregated.bareUsages,
+                entrypointPath,
+                importMap,
+                imports,
+                parseFindings: aggregated.parseFindings,
+                warnings: aggregated.warnings,
+            };
+        })();
+        importGraphCache.set(cacheKey, next);
+        return next;
+    };
+    const getSymbolIndex = () => {
+        if (symbolIndexPromise) {
+            return symbolIndexPromise;
+        }
+        symbolIndexPromise = buildSymbolIndex({
+            getSourceAnalysis,
+            missingRoots: sourceCollection.missingRoots,
+            sourceFiles: sourceCollection.files,
+        });
+        return symbolIndexPromise;
+    };
+    return {
+        entrypointPath,
+        getImportGraphAnalysis,
+        getParsedSourceFile,
+        getSymbolIndex,
+        importMap,
+        missingRoots: sourceCollection.missingRoots,
+        sourceFiles: sourceCollection.files,
+        workspaceRoot: options.workspaceRoot,
+    };
+};
+/**
+ * Projects a filtered symbol view from the cached workspace symbol index.
+ */
+export const selectCandidateSymbols = ({ filter, index, }) => {
+    const matcher = createFilterMatcher(filter);
+    const exportFiles = new Map();
+    for (const [name, filePath] of index.exportFiles.entries()) {
+        if (matcher(name)) {
+            exportFiles.set(name, filePath);
+        }
+    }
+    const symbolNames = [...index.declarations.keys()].filter((name) => matcher(name)).sort(compareStrings);
+    const symbols = [...index.declarations.entries()]
+        .filter(([name]) => matcher(name))
+        .sort(([left], [right]) => compareStrings(left, right))
+        .map(([name, kind]) => ({
+        kind,
+        name,
+    }));
+    return {
+        errors: index.errors,
+        exportFiles,
+        index,
+        symbolNames,
+        symbols,
+        warnings: index.warnings,
+    };
+};