@oicl-lit/analyzer 0.14.1

package/lib/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/lib/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,IAAkB,EAClB,WAAyB,EACzB,SAAiB,EACJ,EAAE;IACf,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,wBAAwB,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,yDAAyD;QACzD,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,wBAAwB,WAAW,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,WAAW,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,WAA0B,CAAC;AACpC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,IAAkB,EAClB,QAA2B,EAC3B,UAAU,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,EAC1B,EAAE;IACF,IAAI,QAAQ,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,GAAG,IAAI,IAAI,GAAG,EAAE,CAAC;QAClC,IAAI,QAAQ,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrC,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,qBAAqB,CAAC,CAAC;AAClE,CAAC,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2022 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\nimport {AnalyzerInterface} from './model.js';\n\n/**\n * An absolute path\n */\nexport type AbsolutePath = string & {\n  __absolutePathBrand: never;\n};\n\n/**\n * A path relative to a package root\n */\nexport type PackagePath = string & {\n  __packagePathBrand: never;\n};\n\n/**\n * Convert an absolute path to a package-relative path\n */\nexport const absoluteToPackage = (\n  path: AbsolutePath,\n  packageRoot: AbsolutePath,\n  seperator: string\n): PackagePath => {\n  if (!path.startsWith(packageRoot)) {\n    throw new Error(`path ${path} is not contained in ${packageRoot}`);\n  }\n  let packagePath = path.substring(packageRoot.length);\n  if (!packageRoot.endsWith(seperator)) {\n    // Make sure we don't have path='/abc/def' and root='/ab'\n    if (!packagePath.startsWith(seperator)) {\n      throw new Error(`path ${path} is not contained in ${packageRoot}`);\n    }\n    packagePath = packagePath.substring(1, packagePath.length);\n  }\n  return packagePath as PackagePath;\n};\n\nexport const resolveExtension = (\n  path: AbsolutePath,\n  analyzer: AnalyzerInterface,\n  extensions = ['js', 'mjs']\n) => {\n  if (analyzer.fs.fileExists(path)) {\n    return path;\n  }\n  for (const ext of extensions) {\n    const fileName = `${path}.${ext}`;\n    if (analyzer.fs.fileExists(fileName)) {\n      return fileName;\n    }\n  }\n  throw new Error(`Could not resolve ${path} to a file on disk.`);\n};\n"]}

package/lib/references.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import type ts from 'typescript';
+import { AnalyzerInterface, LocalNameOrReference, Reference } from './model.js';
+/**
+ * Returns a ts.Symbol for a name in scope at a given location in the AST.
+ * TODO(kschaaf): There are ~1748 symbols in scope of a typical hello world,
+ * due to DOM globals. Perf might become an issue here.
+ */
+export declare const getSymbolForName: (name: string, location: ts.Node, analyzer: AnalyzerInterface) => ts.Symbol | undefined;
+/**
+ * Returns an analyzer `Reference` object for the given identifier.
+ *
+ * If the symbol's declaration was imported, the Reference will be based on
+ * the import's module specifier; otherwise the Reference will point to the
+ * current module being analyzed.
+ */
+export declare const getReferenceForIdentifier: (identifier: ts.Identifier, analyzer: AnalyzerInterface) => Reference | undefined;
+/**
+ * Returns an analyzer `Reference` model for the given ts.Symbol.
+ *
+ * If the symbol's declaration was imported, the Reference will be based on
+ * the import's module specifier; otherwise the Reference will point to the
+ * current module being analyzed.
+ */
+export declare function getReferenceForSymbol(symbol: ts.Symbol, location: ts.Node, analyzer: AnalyzerInterface): Reference | undefined;
+/**
+ * Returns a `Reference` for a symbol that was imported.
+ *
+ * There are 4 main categories of imports we cover:
+ *
+ * 1. A symbol imported from a URL. The declaration will be an
+ *    ImportModuleSpecifier and its module path will be parsable as a URL.
+ *
+ * 2. A symbol imported from a relative file within this package. The
+ *    declaration will be an ImportModuleSpecifier and its module path will
+ *    start with a '.'
+ *
+ * 3. A symbol imported from an absolute path. The declaration will be an
+ *    ImportModuleSpecifier and its module path will start with a '/' This is a
+ *    weird case to cover in the analyzer because it isn't portable.
+ *
+ * 4. A symbol imported from an external package. The declaration will be an
+ *    ImportModuleSpecifier and its module path will not start with a '.'
+ */
+export declare const getImportReference: (specifier: string, location: ts.Node, name: string, analyzer: AnalyzerInterface) => Reference;
+/**
+ * Returns a `Reference` for a symbol that was imported.
+ */
+export declare const getImportReferenceForSpecifierExpression: (specifierExpression: ts.Expression, name: string, analyzer: AnalyzerInterface) => Reference;
+/**
+ * For a given export clause and (optional) specifier from an export statement,
+ * returns an array of objects mapping the export name to a
+ * LocalNameOrReference, which is a string name that can be looked up directly
+ * in `getDeclaration()` of the declaring module for local declarations, or a
+ * `Reference` in the case of re-exported declarations.
+ *
+ * For example:
+ * ```
+ *   import {a} from 'foo';
+ *   const b = 'b';
+ *   const c = 'c';
+ *   export {a as x, b as y, c};
+ * ```
+ * This would return (using pseudo-code for Reference objects):
+ * ```
+ * [
+ *   {name: 'x', reference: new Reference('a', 'foo')},
+ *   {name: 'y', reference: 'b'},
+ *   {name: 'c', reference: 'c'},
+ * ]
+ * ```
+ *
+ * This also handles explicit re-export syntax, which all become References:
+ * ```
+ *   export {a as x, b as y, c} from 'foo';
+ * ```
+ *
+ * Finally, this handles namespace exports, which become a single Reference:
+ * ```
+ *   export * as ns from 'foo';
+ * ```
+ * becomes:
+ * ```
+ *   [{name: 'ns', reference: new Reference('*', 'foo')}]
+ * ```
+ */
+export declare const getExportReferences: (exportClause: ts.NamedExportBindings, moduleSpecifier: ts.Expression | undefined, analyzer: AnalyzerInterface) => Array<{
+    exportName: string;
+    decNameOrRef: LocalNameOrReference;
+}>;
+/**
+ * Returns the specifier string from a specifier expression.
+ *
+ * For a given import statement:
+ * ```
+ * import {foo} from 'foo/bar.js';
+ * ```
+ * The specifierExpression is the string literal 'foo/bar.js' whose getText()
+ * includes the quotes. This function returns the string value without the
+ * quotes.
+ */
+export declare const getSpecifierString: (specifierExpression: ts.Expression) => string;
+//# sourceMappingURL=references.d.ts.map

package/lib/references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/lib/references.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,SAAS,EAEV,MAAM,YAAY,CAAC;AAYpB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,MAAM,EACZ,UAAU,EAAE,CAAC,IAAI,EACjB,UAAU,iBAAiB,KAC1B,EAAE,CAAC,MAAM,GAAG,SAQd,CAAC;AAmCF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,YAAY,EAAE,CAAC,UAAU,EACzB,UAAU,iBAAiB,0BAgB5B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,EAAE,CAAC,MAAM,EACjB,QAAQ,EAAE,EAAE,CAAC,IAAI,EACjB,QAAQ,EAAE,iBAAiB,GAC1B,SAAS,GAAG,SAAS,CAgDvB;AAsBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,GAC7B,WAAW,MAAM,EACjB,UAAU,EAAE,CAAC,IAAI,EACjB,MAAM,MAAM,EACZ,UAAU,iBAAiB,cAuD5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wCAAwC,GACnD,qBAAqB,EAAE,CAAC,UAAU,EAClC,MAAM,MAAM,EACZ,UAAU,iBAAiB,cAI5B,CAAC;AA2BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,mBAAmB,GAC9B,cAAc,EAAE,CAAC,mBAAmB,EACpC,iBAAiB,EAAE,CAAC,UAAU,GAAG,SAAS,EAC1C,UAAU,iBAAiB,KAC1B,KAAK,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,oBAAoB,CAAA;CAAC,CAoFhE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,qBAAqB,EAAE,CAAC,UAAU,WAIpE,CAAC"}

package/lib/references.js

@@ -0,0 +1,345 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { Reference, } from './model.js';
+import { getResolvedExportFromSourcePath, getPathForModuleSpecifier, getModuleInfo, } from './javascript/modules.js';
+import { createDiagnostic } from './errors.js';
+import { DiagnosticCode } from './diagnostic-code.js';
+const npmModule = /^(?<package>(@[^/]+\/[^/]+)|[^/]+)\/?(?<module>.*)$/;
+/**
+ * Returns a ts.Symbol for a name in scope at a given location in the AST.
+ * TODO(kschaaf): There are ~1748 symbols in scope of a typical hello world,
+ * due to DOM globals. Perf might become an issue here.
+ */
+export const getSymbolForName = (name, location, analyzer) => {
+    return analyzer.program
+        .getTypeChecker()
+        .getSymbolsInScope(location, analyzer.typescript.SymbolFlags.All)
+        .filter((s) => s.name === name)[0];
+};
+/**
+ * Returns the module specifier expression for a declaration if it was imported,
+ * or `undefined` if the declaration was not imported.
+ */
+const getImportSpecifierInfo = (ts, declaration) => {
+    // TODO(kschaaf) support the various import syntaxes, e.g. `import {foo as bar} from 'baz'`
+    if (ts.isImportSpecifier(declaration) &&
+        ts.isNamedImports(declaration.parent) &&
+        ts.isImportClause(declaration.parent.parent) &&
+        ts.isImportDeclaration(declaration.parent.parent.parent)) {
+        const specifierExpression = declaration.parent.parent.parent.moduleSpecifier;
+        const specifier = getSpecifierString(specifierExpression);
+        return {
+            specifier,
+            location: specifierExpression,
+            name: declaration.propertyName?.text ?? declaration.name.text,
+        };
+    }
+    return undefined;
+};
+/**
+ * Returns an analyzer `Reference` object for the given identifier.
+ *
+ * If the symbol's declaration was imported, the Reference will be based on
+ * the import's module specifier; otherwise the Reference will point to the
+ * current module being analyzed.
+ */
+export const getReferenceForIdentifier = (identifier, analyzer) => {
+    const symbol = analyzer.program
+        .getTypeChecker()
+        .getSymbolAtLocation(identifier);
+    if (symbol === undefined) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: identifier,
+            message: `Could not find symbol for identifier.`,
+        }));
+        return undefined;
+    }
+    return getReferenceForSymbol(symbol, identifier, analyzer);
+};
+/**
+ * Returns an analyzer `Reference` model for the given ts.Symbol.
+ *
+ * If the symbol's declaration was imported, the Reference will be based on
+ * the import's module specifier; otherwise the Reference will point to the
+ * current module being analyzed.
+ */
+export function getReferenceForSymbol(symbol, location, analyzer) {
+    const { name: symbolName } = symbol;
+    // TODO(kschaaf): Do we need to check other declarations? The assumption is
+    // that even with multiple declarations (e.g. because of class interface +
+    // constructor), the reference would point to the same location for all,
+    // or else (in the case of e.g. namespace augmentation) it will be global
+    // and not need a specific module specifier.
+    const declaration = symbol?.declarations?.[0];
+    if (declaration === undefined) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: location,
+            message: `Could not find declaration for symbol '${symbolName}'`,
+        }));
+        return undefined;
+    }
+    const declarationSourceFile = declaration.getSourceFile();
+    const locationSourceFile = location.getSourceFile();
+    // There are three top-level cases to cover:
+    // 1. A global symbol that wasn't imported.
+    // 2. An imported symbol
+    // 3. A symbol declared in this file.
+    if (declarationSourceFile !== locationSourceFile) {
+        // If the reference declaration doesn't exist in this module, it must have
+        // been a global (whose declaration is in an ambient .d.ts file)
+        // TODO(kschaaf): We might want to further differentiate e.g. DOM globals
+        // (that don't have any e.g. source to link to) from other ambient
+        // declarations where we could at least point to a declaration file
+        return getGlobalReference(declarationSourceFile, symbolName, analyzer);
+    }
+    else {
+        // For all other cases, the symbol's declaration node will be in this file,
+        // either as an ImportDeclaration or a normal declaration.
+        const importInfo = getImportSpecifierInfo(analyzer.typescript, declaration);
+        if (importInfo !== undefined) {
+            // Declaration was imported
+            return getImportReference(importInfo.specifier, importInfo.location, importInfo.name, analyzer);
+        }
+        else {
+            // Declared in this file: use the current package and module
+            return getLocalReference(location, symbolName, analyzer);
+        }
+    }
+}
+/**
+ * Returns a `Reference` for a global symbol that was not imported.
+ */
+const getGlobalReference = (declarationSourceFile, name, analyzer) => {
+    return new Reference({
+        name,
+        isGlobal: true,
+        dereference: () => getResolvedExportFromSourcePath(declarationSourceFile.fileName, name, analyzer),
+    });
+};
+/**
+ * Returns a `Reference` for a symbol that was imported.
+ *
+ * There are 4 main categories of imports we cover:
+ *
+ * 1. A symbol imported from a URL. The declaration will be an
+ *    ImportModuleSpecifier and its module path will be parsable as a URL.
+ *
+ * 2. A symbol imported from a relative file within this package. The
+ *    declaration will be an ImportModuleSpecifier and its module path will
+ *    start with a '.'
+ *
+ * 3. A symbol imported from an absolute path. The declaration will be an
+ *    ImportModuleSpecifier and its module path will start with a '/' This is a
+ *    weird case to cover in the analyzer because it isn't portable.
+ *
+ * 4. A symbol imported from an external package. The declaration will be an
+ *    ImportModuleSpecifier and its module path will not start with a '.'
+ */
+export const getImportReference = (specifier, location, name, analyzer) => {
+    const { path } = analyzer;
+    let refPackage;
+    let refModule;
+    // Check whether it is a URL, absolute, package local, or external
+    try {
+        new URL(specifier);
+        refPackage = '';
+        refModule = specifier;
+    }
+    catch {
+        if (specifier[0] === '.') {
+            // Relative import from this package: use the current package and
+            // module path relative to this module
+            const sourceFilePath = location.getSourceFile().fileName;
+            const module = getModuleInfo(sourceFilePath, analyzer);
+            refPackage = module.packageJson.name;
+            refModule = path
+                .join(path.dirname(module.jsPath), specifier)
+                .replace(/\\/g, '/');
+        }
+        else if (analyzer.path.isAbsolute(specifier)) {
+            // Absolute import; no package, just use the entire path as the
+            // module
+            refPackage = '';
+            refModule = specifier;
+        }
+        else {
+            // External import: extract the npm package (taking care to respect
+            // npm orgs) and module specifier (if any)
+            const info = specifier.match(npmModule);
+            if (info?.groups) {
+                refPackage = info.groups.package;
+                refModule = info.groups.module || undefined;
+            }
+            else {
+                analyzer.addDiagnostic(createDiagnostic({
+                    typescript: analyzer.typescript,
+                    node: location,
+                    message: `External npm package could not be parsed from module specifier '${specifier}'.`,
+                }));
+            }
+        }
+    }
+    return new Reference({
+        name,
+        package: refPackage,
+        module: refModule,
+        dereference: () => {
+            const path = getPathForModuleSpecifier(specifier, location, analyzer);
+            if (path === undefined) {
+                return;
+            }
+            return getResolvedExportFromSourcePath(path, name, analyzer);
+        },
+    });
+};
+/**
+ * Returns a `Reference` for a symbol that was imported.
+ */
+export const getImportReferenceForSpecifierExpression = (specifierExpression, name, analyzer) => {
+    const specifier = getSpecifierString(specifierExpression);
+    return getImportReference(specifier, specifierExpression, name, analyzer);
+};
+/**
+ * Returns a `Reference` to a symbol declared in the current source file.
+ */
+const getLocalReference = (location, name, analyzer) => {
+    const module = getModuleInfo(location.getSourceFile().fileName, analyzer);
+    return new Reference({
+        name,
+        package: module.packageJson.name,
+        module: module.jsPath.replace(/\\/g, '/'),
+        dereference: () => getResolvedExportFromSourcePath(location.getSourceFile().fileName, name, analyzer),
+    });
+};
+/**
+ * For a given export clause and (optional) specifier from an export statement,
+ * returns an array of objects mapping the export name to a
+ * LocalNameOrReference, which is a string name that can be looked up directly
+ * in `getDeclaration()` of the declaring module for local declarations, or a
+ * `Reference` in the case of re-exported declarations.
+ *
+ * For example:
+ * ```
+ *   import {a} from 'foo';
+ *   const b = 'b';
+ *   const c = 'c';
+ *   export {a as x, b as y, c};
+ * ```
+ * This would return (using pseudo-code for Reference objects):
+ * ```
+ * [
+ *   {name: 'x', reference: new Reference('a', 'foo')},
+ *   {name: 'y', reference: 'b'},
+ *   {name: 'c', reference: 'c'},
+ * ]
+ * ```
+ *
+ * This also handles explicit re-export syntax, which all become References:
+ * ```
+ *   export {a as x, b as y, c} from 'foo';
+ * ```
+ *
+ * Finally, this handles namespace exports, which become a single Reference:
+ * ```
+ *   export * as ns from 'foo';
+ * ```
+ * becomes:
+ * ```
+ *   [{name: 'ns', reference: new Reference('*', 'foo')}]
+ * ```
+ */
+export const getExportReferences = (exportClause, moduleSpecifier, analyzer) => {
+    const { typescript } = analyzer;
+    const refs = [];
+    if (typescript.isNamedExports(exportClause)) {
+        for (const el of exportClause.elements) {
+            const exportName = el.name.getText();
+            const localNameNode = el.propertyName ?? el.name;
+            const localName = localNameNode.getText();
+            if (moduleSpecifier !== undefined) {
+                // This was an explicit re-export (e.g. `export {a} from 'foo'`), so add
+                // a Reference
+                const specifier = getSpecifierString(moduleSpecifier);
+                refs.push({
+                    exportName,
+                    decNameOrRef: getImportReference(specifier, moduleSpecifier, localName, analyzer),
+                });
+            }
+            else {
+                // Get the declaration for this symbol, so we can determine if
+                // it was declared locally or not. Note we use name-based searching
+                // to find the symbol, because `getSymbolAtLocation()` for
+                // `export {Foo}` will annoyingly just point back to the export
+                // line, rather than the location it was actually declared.
+                const symbol = getSymbolForName(localName, localNameNode, analyzer);
+                const decl = symbol?.declarations?.[0];
+                if (symbol === undefined || decl === undefined) {
+                    analyzer.addDiagnostic(createDiagnostic({
+                        typescript,
+                        node: el,
+                        message: `Could not find declaration for symbol`,
+                    }));
+                    continue;
+                }
+                if (typescript.isImportSpecifier(decl)) {
+                    // If the declaration was an import specifier, this means it's being
+                    // re-exported, so add a Reference
+                    const ref = getReferenceForSymbol(symbol, decl, analyzer);
+                    if (ref !== undefined) {
+                        refs.push({
+                            exportName,
+                            decNameOrRef: ref,
+                        });
+                    }
+                }
+                else {
+                    // Otherwise, the declaration is local, so just add its name; this
+                    // can be looked up directly in `getDeclaration` for the module
+                    refs.push({ exportName, decNameOrRef: localName });
+                }
+            }
+        }
+    }
+    else if (
+    // e.g. `export * as ns from 'foo'`;
+    typescript.isNamespaceExport(exportClause) &&
+        moduleSpecifier !== undefined) {
+        const specifier = getSpecifierString(moduleSpecifier);
+        refs.push({
+            exportName: exportClause.name.getText(),
+            decNameOrRef: getImportReference(specifier, moduleSpecifier, '*', analyzer),
+        });
+    }
+    else {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript,
+            node: exportClause,
+            message: `Unhandled form of ExportDeclaration`,
+            category: typescript.DiagnosticCategory.Warning,
+            code: DiagnosticCode.UNSUPPORTED,
+        }));
+    }
+    return refs;
+};
+/**
+ * Returns the specifier string from a specifier expression.
+ *
+ * For a given import statement:
+ * ```
+ * import {foo} from 'foo/bar.js';
+ * ```
+ * The specifierExpression is the string literal 'foo/bar.js' whose getText()
+ * includes the quotes. This function returns the string value without the
+ * quotes.
+ */
+export const getSpecifierString = (specifierExpression) => {
+    // A specifier expression is always expected to be a quoted string literal.
+    // Slice off the quotes and return the text.
+    return specifierExpression.getText().slice(1, -1);
+};
+//# sourceMappingURL=references.js.map

package/lib/references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.js","sourceRoot":"","sources":["../src/lib/references.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAGL,SAAS,GAEV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,EACzB,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,gBAAgB,EAAC,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAC,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAEpD,MAAM,SAAS,GAAG,qDAAqD,CAAC;AAExE;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,IAAY,EACZ,QAAiB,EACjB,QAA2B,EACJ,EAAE;IACzB,OAAO,QAAQ,CAAC,OAAO;SACpB,cAAc,EAAE;SAChB,iBAAiB,CAChB,QAAQ,EACP,QAAQ,CAAC,UAAU,CAAC,WAAwC,CAAC,GAAG,CAClE;SACA,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC,CAAC;AAQF;;;GAGG;AACH,MAAM,sBAAsB,GAAG,CAC7B,EAAc,EACd,WAAoB,EACa,EAAE;IACnC,2FAA2F;IAC3F,IACE,EAAE,CAAC,iBAAiB,CAAC,WAAW,CAAC;QACjC,EAAE,CAAC,cAAc,CAAC,WAAW,CAAC,MAAM,CAAC;QACrC,EAAE,CAAC,cAAc,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC;QAC5C,EAAE,CAAC,mBAAmB,CAAC,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EACxD,CAAC;QACD,MAAM,mBAAmB,GACvB,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC;QACnD,MAAM,SAAS,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,CAAC;QAC1D,OAAO;YACL,SAAS;YACT,QAAQ,EAAE,mBAAmB;YAC7B,IAAI,EAAE,WAAW,CAAC,YAAY,EAAE,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI;SAC9D,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,UAAyB,EACzB,QAA2B,EAC3B,EAAE;IACF,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO;SAC5B,cAAc,EAAE;SAChB,mBAAmB,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,QAAQ,CAAC,aAAa,CACpB,gBAAgB,CAAC;YACf,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,uCAAuC;SACjD,CAAC,CACH,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AAC7D,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,QAAiB,EACjB,QAA2B;IAE3B,MAAM,EAAC,IAAI,EAAE,UAAU,EAAC,GAAG,MAAM,CAAC;IAClC,2EAA2E;IAC3E,0EAA0E;IAC1E,wEAAwE;IACxE,yEAAyE;IACzE,4CAA4C;IAC5C,MAAM,WAAW,GAAG,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,QAAQ,CAAC,aAAa,CACpB,gBAAgB,CAAC;YACf,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,0CAA0C,UAAU,GAAG;SACjE,CAAC,CACH,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,qBAAqB,GAAG,WAAW,CAAC,aAAa,EAAE,CAAC;IAC1D,MAAM,kBAAkB,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;IACpD,4CAA4C;IAC5C,2CAA2C;IAC3C,wBAAwB;IACxB,qCAAqC;IACrC,IAAI,qBAAqB,KAAK,kBAAkB,EAAE,CAAC;QACjD,0EAA0E;QAC1E,gEAAgE;QAChE,yEAAyE;QACzE,kEAAkE;QAClE,mEAAmE;QACnE,OAAO,kBAAkB,CAAC,qBAAqB,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IACzE,CAAC;SAAM,CAAC;QACN,2EAA2E;QAC3E,0DAA0D;QAC1D,MAAM,UAAU,GAAG,sBAAsB,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QAC5E,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,2BAA2B;YAC3B,OAAO,kBAAkB,CACvB,UAAU,CAAC,SAAS,EACpB,UAAU,CAAC,QAAQ,EACnB,UAAU,CAAC,IAAI,EACf,QAAQ,CACT,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,4DAA4D;YAC5D,OAAO,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,kBAAkB,GAAG,CACzB,qBAAoC,EACpC,IAAY,EACZ,QAA2B,EAC3B,EAAE;IACF,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI;QACJ,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,GAAG,EAAE,CAChB,+BAA+B,CAC7B,qBAAqB,CAAC,QAAwB,EAC9C,IAAI,EACJ,QAAQ,CACT;KACJ,CAAC,CAAC;AACL,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,SAAiB,EACjB,QAAiB,EACjB,IAAY,EACZ,QAA2B,EAC3B,EAAE;IACF,MAAM,EAAC,IAAI,EAAC,GAAG,QAAQ,CAAC;IACxB,IAAI,UAAU,CAAC;IACf,IAAI,SAAS,CAAC;IACd,kEAAkE;IAClE,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QACnB,UAAU,GAAG,EAAE,CAAC;QAChB,SAAS,GAAG,SAAS,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YACzB,iEAAiE;YACjE,sCAAsC;YACtC,MAAM,cAAc,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAwB,CAAC;YACzE,MAAM,MAAM,GAAG,aAAa,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;YACvD,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;YACrC,SAAS,GAAG,IAAI;iBACb,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;iBAC5C,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACzB,CAAC;aAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/C,+DAA+D;YAC/D,SAAS;YACT,UAAU,GAAG,EAAE,CAAC;YAChB,SAAS,GAAG,SAAS,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,mEAAmE;YACnE,0CAA0C;YAC1C,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACxC,IAAI,IAAI,EAAE,MAAM,EAAE,CAAC;gBACjB,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;gBACjC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,SAAS,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,aAAa,CACpB,gBAAgB,CAAC;oBACf,UAAU,EAAE,QAAQ,CAAC,UAAU;oBAC/B,IAAI,EAAE,QAAQ;oBACd,OAAO,EAAE,mEAAmE,SAAS,IAAI;iBAC1F,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI;QACJ,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,GAAG,EAAE;YAChB,MAAM,IAAI,GAAG,yBAAyB,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YACtE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO;YACT,CAAC;YACD,OAAO,+BAA+B,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC/D,CAAC;KACF,CAAC,CAAC;AACL,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,CACtD,mBAAkC,EAClC,IAAY,EACZ,QAA2B,EAC3B,EAAE;IACF,MAAM,SAAS,GAAG,kBAAkB,CAAC,mBAAmB,CAAC,CAAC;IAC1D,OAAO,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;AAC5E,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,iBAAiB,GAAG,CACxB,QAAiB,EACjB,IAAY,EACZ,QAA2B,EAC3B,EAAE;IACF,MAAM,MAAM,GAAG,aAAa,CAC1B,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAwB,EACjD,QAAQ,CACT,CAAC;IACF,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI;QACJ,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI;QAChC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;QACzC,WAAW,EAAE,GAAG,EAAE,CAChB,+BAA+B,CAC7B,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAwB,EACjD,IAAI,EACJ,QAAQ,CACT;KACJ,CAAC,CAAC;AACL,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,YAAoC,EACpC,eAA0C,EAC1C,QAA2B,EACsC,EAAE;IACnE,MAAM,EAAC,UAAU,EAAC,GAAG,QAAQ,CAAC;IAC9B,MAAM,IAAI,GACR,EAAE,CAAC;IACL,IAAI,UAAU,CAAC,cAAc,CAAC,YAAY,CAAC,EAAE,CAAC;QAC5C,KAAK,MAAM,EAAE,IAAI,YAAY,CAAC,QAAQ,EAAE,CAAC;YACvC,MAAM,UAAU,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,IAAI,EAAE,CAAC,IAAI,CAAC;YACjD,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,EAAE,CAAC;YAC1C,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;gBAClC,wEAAwE;gBACxE,cAAc;gBACd,MAAM,SAAS,GAAG,kBAAkB,CAAC,eAAe,CAAC,CAAC;gBACtD,IAAI,CAAC,IAAI,CAAC;oBACR,UAAU;oBACV,YAAY,EAAE,kBAAkB,CAC9B,SAAS,EACT,eAAe,EACf,SAAS,EACT,QAAQ,CACT;iBACF,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,8DAA8D;gBAC9D,mEAAmE;gBACnE,0DAA0D;gBAC1D,+DAA+D;gBAC/D,2DAA2D;gBAC3D,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;gBACpE,MAAM,IAAI,GAAG,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;gBACvC,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBAC/C,QAAQ,CAAC,aAAa,CACpB,gBAAgB,CAAC;wBACf,UAAU;wBACV,IAAI,EAAE,EAAE;wBACR,OAAO,EAAE,uCAAuC;qBACjD,CAAC,CACH,CAAC;oBACF,SAAS;gBACX,CAAC;gBACD,IAAI,UAAU,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;oBACvC,oEAAoE;oBACpE,kCAAkC;oBAClC,MAAM,GAAG,GAAG,qBAAqB,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;oBAC1D,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;wBACtB,IAAI,CAAC,IAAI,CAAC;4BACR,UAAU;4BACV,YAAY,EAAE,GAAG;yBAClB,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,kEAAkE;oBAClE,+DAA+D;oBAC/D,IAAI,CAAC,IAAI,CAAC,EAAC,UAAU,EAAE,YAAY,EAAE,SAAS,EAAC,CAAC,CAAC;gBACnD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;SAAM;IACL,oCAAoC;IACpC,UAAU,CAAC,iBAAiB,CAAC,YAAY,CAAC;QAC1C,eAAe,KAAK,SAAS,EAC7B,CAAC;QACD,MAAM,SAAS,GAAG,kBAAkB,CAAC,eAAe,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,CAAC;YACR,UAAU,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE;YACvC,YAAY,EAAE,kBAAkB,CAC9B,SAAS,EACT,eAAe,EACf,GAAG,EACH,QAAQ,CACT;SACF,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,aAAa,CACpB,gBAAgB,CAAC;YACf,UAAU;YACV,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,qCAAqC;YAC9C,QAAQ,EAAE,UAAU,CAAC,kBAAkB,CAAC,OAAO;YAC/C,IAAI,EAAE,cAAc,CAAC,WAAW;SACjC,CAAC,CACH,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,mBAAkC,EAAE,EAAE;IACvE,2EAA2E;IAC3E,4CAA4C;IAC5C,OAAO,mBAAmB,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2022 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\nimport type ts from 'typescript';\nimport {\n  AnalyzerInterface,\n  LocalNameOrReference,\n  Reference,\n  TypeScript,\n} from './model.js';\nimport {\n  getResolvedExportFromSourcePath,\n  getPathForModuleSpecifier,\n  getModuleInfo,\n} from './javascript/modules.js';\nimport {AbsolutePath} from './paths.js';\nimport {createDiagnostic} from './errors.js';\nimport {DiagnosticCode} from './diagnostic-code.js';\n\nconst npmModule = /^(?<package>(@[^/]+\\/[^/]+)|[^/]+)\\/?(?<module>.*)$/;\n\n/**\n * Returns a ts.Symbol for a name in scope at a given location in the AST.\n * TODO(kschaaf): There are ~1748 symbols in scope of a typical hello world,\n * due to DOM globals. Perf might become an issue here.\n */\nexport const getSymbolForName = (\n  name: string,\n  location: ts.Node,\n  analyzer: AnalyzerInterface\n): ts.Symbol | undefined => {\n  return analyzer.program\n    .getTypeChecker()\n    .getSymbolsInScope(\n      location,\n      (analyzer.typescript.SymbolFlags as unknown as {All: number}).All\n    )\n    .filter((s) => s.name === name)[0];\n};\n\ninterface ModuleSpecifierInfo {\n  specifier: string;\n  location: ts.Node;\n  name: string;\n}\n\n/**\n * Returns the module specifier expression for a declaration if it was imported,\n * or `undefined` if the declaration was not imported.\n */\nconst getImportSpecifierInfo = (\n  ts: TypeScript,\n  declaration: ts.Node\n): ModuleSpecifierInfo | undefined => {\n  // TODO(kschaaf) support the various import syntaxes, e.g. `import {foo as bar} from 'baz'`\n  if (\n    ts.isImportSpecifier(declaration) &&\n    ts.isNamedImports(declaration.parent) &&\n    ts.isImportClause(declaration.parent.parent) &&\n    ts.isImportDeclaration(declaration.parent.parent.parent)\n  ) {\n    const specifierExpression =\n      declaration.parent.parent.parent.moduleSpecifier;\n    const specifier = getSpecifierString(specifierExpression);\n    return {\n      specifier,\n      location: specifierExpression,\n      name: declaration.propertyName?.text ?? declaration.name.text,\n    };\n  }\n  return undefined;\n};\n\n/**\n * Returns an analyzer `Reference` object for the given identifier.\n *\n * If the symbol's declaration was imported, the Reference will be based on\n * the import's module specifier; otherwise the Reference will point to the\n * current module being analyzed.\n */\nexport const getReferenceForIdentifier = (\n  identifier: ts.Identifier,\n  analyzer: AnalyzerInterface\n) => {\n  const symbol = analyzer.program\n    .getTypeChecker()\n    .getSymbolAtLocation(identifier);\n  if (symbol === undefined) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: identifier,\n        message: `Could not find symbol for identifier.`,\n      })\n    );\n    return undefined;\n  }\n  return getReferenceForSymbol(symbol, identifier, analyzer);\n};\n\n/**\n * Returns an analyzer `Reference` model for the given ts.Symbol.\n *\n * If the symbol's declaration was imported, the Reference will be based on\n * the import's module specifier; otherwise the Reference will point to the\n * current module being analyzed.\n */\nexport function getReferenceForSymbol(\n  symbol: ts.Symbol,\n  location: ts.Node,\n  analyzer: AnalyzerInterface\n): Reference | undefined {\n  const {name: symbolName} = symbol;\n  // TODO(kschaaf): Do we need to check other declarations? The assumption is\n  // that even with multiple declarations (e.g. because of class interface +\n  // constructor), the reference would point to the same location for all,\n  // or else (in the case of e.g. namespace augmentation) it will be global\n  // and not need a specific module specifier.\n  const declaration = symbol?.declarations?.[0];\n  if (declaration === undefined) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: location,\n        message: `Could not find declaration for symbol '${symbolName}'`,\n      })\n    );\n    return undefined;\n  }\n  const declarationSourceFile = declaration.getSourceFile();\n  const locationSourceFile = location.getSourceFile();\n  // There are three top-level cases to cover:\n  // 1. A global symbol that wasn't imported.\n  // 2. An imported symbol\n  // 3. A symbol declared in this file.\n  if (declarationSourceFile !== locationSourceFile) {\n    // If the reference declaration doesn't exist in this module, it must have\n    // been a global (whose declaration is in an ambient .d.ts file)\n    // TODO(kschaaf): We might want to further differentiate e.g. DOM globals\n    // (that don't have any e.g. source to link to) from other ambient\n    // declarations where we could at least point to a declaration file\n    return getGlobalReference(declarationSourceFile, symbolName, analyzer);\n  } else {\n    // For all other cases, the symbol's declaration node will be in this file,\n    // either as an ImportDeclaration or a normal declaration.\n    const importInfo = getImportSpecifierInfo(analyzer.typescript, declaration);\n    if (importInfo !== undefined) {\n      // Declaration was imported\n      return getImportReference(\n        importInfo.specifier,\n        importInfo.location,\n        importInfo.name,\n        analyzer\n      );\n    } else {\n      // Declared in this file: use the current package and module\n      return getLocalReference(location, symbolName, analyzer);\n    }\n  }\n}\n\n/**\n * Returns a `Reference` for a global symbol that was not imported.\n */\nconst getGlobalReference = (\n  declarationSourceFile: ts.SourceFile,\n  name: string,\n  analyzer: AnalyzerInterface\n) => {\n  return new Reference({\n    name,\n    isGlobal: true,\n    dereference: () =>\n      getResolvedExportFromSourcePath(\n        declarationSourceFile.fileName as AbsolutePath,\n        name,\n        analyzer\n      ),\n  });\n};\n\n/**\n * Returns a `Reference` for a symbol that was imported.\n *\n * There are 4 main categories of imports we cover:\n *\n * 1. A symbol imported from a URL. The declaration will be an\n *    ImportModuleSpecifier and its module path will be parsable as a URL.\n *\n * 2. A symbol imported from a relative file within this package. The\n *    declaration will be an ImportModuleSpecifier and its module path will\n *    start with a '.'\n *\n * 3. A symbol imported from an absolute path. The declaration will be an\n *    ImportModuleSpecifier and its module path will start with a '/' This is a\n *    weird case to cover in the analyzer because it isn't portable.\n *\n * 4. A symbol imported from an external package. The declaration will be an\n *    ImportModuleSpecifier and its module path will not start with a '.'\n */\nexport const getImportReference = (\n  specifier: string,\n  location: ts.Node,\n  name: string,\n  analyzer: AnalyzerInterface\n) => {\n  const {path} = analyzer;\n  let refPackage;\n  let refModule;\n  // Check whether it is a URL, absolute, package local, or external\n  try {\n    new URL(specifier);\n    refPackage = '';\n    refModule = specifier;\n  } catch {\n    if (specifier[0] === '.') {\n      // Relative import from this package: use the current package and\n      // module path relative to this module\n      const sourceFilePath = location.getSourceFile().fileName as AbsolutePath;\n      const module = getModuleInfo(sourceFilePath, analyzer);\n      refPackage = module.packageJson.name;\n      refModule = path\n        .join(path.dirname(module.jsPath), specifier)\n        .replace(/\\\\/g, '/');\n    } else if (analyzer.path.isAbsolute(specifier)) {\n      // Absolute import; no package, just use the entire path as the\n      // module\n      refPackage = '';\n      refModule = specifier;\n    } else {\n      // External import: extract the npm package (taking care to respect\n      // npm orgs) and module specifier (if any)\n      const info = specifier.match(npmModule);\n      if (info?.groups) {\n        refPackage = info.groups.package;\n        refModule = info.groups.module || undefined;\n      } else {\n        analyzer.addDiagnostic(\n          createDiagnostic({\n            typescript: analyzer.typescript,\n            node: location,\n            message: `External npm package could not be parsed from module specifier '${specifier}'.`,\n          })\n        );\n      }\n    }\n  }\n  return new Reference({\n    name,\n    package: refPackage,\n    module: refModule,\n    dereference: () => {\n      const path = getPathForModuleSpecifier(specifier, location, analyzer);\n      if (path === undefined) {\n        return;\n      }\n      return getResolvedExportFromSourcePath(path, name, analyzer);\n    },\n  });\n};\n\n/**\n * Returns a `Reference` for a symbol that was imported.\n */\nexport const getImportReferenceForSpecifierExpression = (\n  specifierExpression: ts.Expression,\n  name: string,\n  analyzer: AnalyzerInterface\n) => {\n  const specifier = getSpecifierString(specifierExpression);\n  return getImportReference(specifier, specifierExpression, name, analyzer);\n};\n\n/**\n * Returns a `Reference` to a symbol declared in the current source file.\n */\nconst getLocalReference = (\n  location: ts.Node,\n  name: string,\n  analyzer: AnalyzerInterface\n) => {\n  const module = getModuleInfo(\n    location.getSourceFile().fileName as AbsolutePath,\n    analyzer\n  );\n  return new Reference({\n    name,\n    package: module.packageJson.name,\n    module: module.jsPath.replace(/\\\\/g, '/'),\n    dereference: () =>\n      getResolvedExportFromSourcePath(\n        location.getSourceFile().fileName as AbsolutePath,\n        name,\n        analyzer\n      ),\n  });\n};\n\n/**\n * For a given export clause and (optional) specifier from an export statement,\n * returns an array of objects mapping the export name to a\n * LocalNameOrReference, which is a string name that can be looked up directly\n * in `getDeclaration()` of the declaring module for local declarations, or a\n * `Reference` in the case of re-exported declarations.\n *\n * For example:\n * ```\n *   import {a} from 'foo';\n *   const b = 'b';\n *   const c = 'c';\n *   export {a as x, b as y, c};\n * ```\n * This would return (using pseudo-code for Reference objects):\n * ```\n * [\n *   {name: 'x', reference: new Reference('a', 'foo')},\n *   {name: 'y', reference: 'b'},\n *   {name: 'c', reference: 'c'},\n * ]\n * ```\n *\n * This also handles explicit re-export syntax, which all become References:\n * ```\n *   export {a as x, b as y, c} from 'foo';\n * ```\n *\n * Finally, this handles namespace exports, which become a single Reference:\n * ```\n *   export * as ns from 'foo';\n * ```\n * becomes:\n * ```\n *   [{name: 'ns', reference: new Reference('*', 'foo')}]\n * ```\n */\nexport const getExportReferences = (\n  exportClause: ts.NamedExportBindings,\n  moduleSpecifier: ts.Expression | undefined,\n  analyzer: AnalyzerInterface\n): Array<{exportName: string; decNameOrRef: LocalNameOrReference}> => {\n  const {typescript} = analyzer;\n  const refs: Array<{exportName: string; decNameOrRef: string | Reference}> =\n    [];\n  if (typescript.isNamedExports(exportClause)) {\n    for (const el of exportClause.elements) {\n      const exportName = el.name.getText();\n      const localNameNode = el.propertyName ?? el.name;\n      const localName = localNameNode.getText();\n      if (moduleSpecifier !== undefined) {\n        // This was an explicit re-export (e.g. `export {a} from 'foo'`), so add\n        // a Reference\n        const specifier = getSpecifierString(moduleSpecifier);\n        refs.push({\n          exportName,\n          decNameOrRef: getImportReference(\n            specifier,\n            moduleSpecifier,\n            localName,\n            analyzer\n          ),\n        });\n      } else {\n        // Get the declaration for this symbol, so we can determine if\n        // it was declared locally or not. Note we use name-based searching\n        // to find the symbol, because `getSymbolAtLocation()` for\n        // `export {Foo}` will annoyingly just point back to the export\n        // line, rather than the location it was actually declared.\n        const symbol = getSymbolForName(localName, localNameNode, analyzer);\n        const decl = symbol?.declarations?.[0];\n        if (symbol === undefined || decl === undefined) {\n          analyzer.addDiagnostic(\n            createDiagnostic({\n              typescript,\n              node: el,\n              message: `Could not find declaration for symbol`,\n            })\n          );\n          continue;\n        }\n        if (typescript.isImportSpecifier(decl)) {\n          // If the declaration was an import specifier, this means it's being\n          // re-exported, so add a Reference\n          const ref = getReferenceForSymbol(symbol, decl, analyzer);\n          if (ref !== undefined) {\n            refs.push({\n              exportName,\n              decNameOrRef: ref,\n            });\n          }\n        } else {\n          // Otherwise, the declaration is local, so just add its name; this\n          // can be looked up directly in `getDeclaration` for the module\n          refs.push({exportName, decNameOrRef: localName});\n        }\n      }\n    }\n  } else if (\n    // e.g. `export * as ns from 'foo'`;\n    typescript.isNamespaceExport(exportClause) &&\n    moduleSpecifier !== undefined\n  ) {\n    const specifier = getSpecifierString(moduleSpecifier);\n    refs.push({\n      exportName: exportClause.name.getText(),\n      decNameOrRef: getImportReference(\n        specifier,\n        moduleSpecifier,\n        '*',\n        analyzer\n      ),\n    });\n  } else {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript,\n        node: exportClause,\n        message: `Unhandled form of ExportDeclaration`,\n        category: typescript.DiagnosticCategory.Warning,\n        code: DiagnosticCode.UNSUPPORTED,\n      })\n    );\n  }\n  return refs;\n};\n\n/**\n * Returns the specifier string from a specifier expression.\n *\n * For a given import statement:\n * ```\n * import {foo} from 'foo/bar.js';\n * ```\n * The specifierExpression is the string literal 'foo/bar.js' whose getText()\n * includes the quotes. This function returns the string value without the\n * quotes.\n */\nexport const getSpecifierString = (specifierExpression: ts.Expression) => {\n  // A specifier expression is always expected to be a quoted string literal.\n  // Slice off the quotes and return the text.\n  return specifierExpression.getText().slice(1, -1);\n};\n"]}

package/lib/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import type ts from 'typescript';
+import { Type, AnalyzerInterface } from './model.js';
+export type TypeScript = typeof ts;
+/**
+ * Returns an analyzer `Type` object for the given type string,
+ * evaluated at the given location.
+ *
+ * Used for parsing types from JSDoc.
+ */
+export declare const getTypeForTypeString: (typeString: string, location: ts.Node, analyzer: AnalyzerInterface) => Type | undefined;
+/**
+ * Returns an analyzer `Type` object for the given AST node.
+ */
+export declare const getTypeForNode: (node: ts.Node, analyzer: AnalyzerInterface) => Type;
+/**
+ * Converts a ts.Type into an analyzer Type object (which wraps
+ * the ts.Type, but also provides analyzer Reference objects).
+ */
+export declare const getTypeForType: (type: ts.Type, location: ts.Node, analyzer: AnalyzerInterface) => Type;
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAC,IAAI,EAAa,iBAAiB,EAAC,MAAM,YAAY,CAAC;AAc9D,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,MAAM,EAClB,UAAU,EAAE,CAAC,IAAI,EACjB,UAAU,iBAAiB,KAC1B,IAAI,GAAG,SAyBT,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,EAAE,CAAC,IAAI,EACb,UAAU,iBAAiB,KAC1B,IAMF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,EAAE,CAAC,IAAI,EACb,UAAU,EAAE,CAAC,IAAI,EACjB,UAAU,iBAAiB,KAC1B,IAkCF,CAAC"}