@oicl-lit/analyzer 0.14.1

package/lib/javascript/modules.js

@@ -0,0 +1,277 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { Module, } from '../model.js';
+import { getClassDeclarationInfo } from './classes.js';
+import { getExportAssignmentVariableDeclarationInfo, getVariableDeclarationInfo, getEnumDeclarationInfo, } from './variables.js';
+import { absoluteToPackage } from '../paths.js';
+import { getPackageInfo } from './packages.js';
+import { createDiagnostic } from '../errors.js';
+import { getExportReferences, getImportReferenceForSpecifierExpression, getSpecifierString, } from '../references.js';
+import { parseModuleJSDocInfo } from './jsdoc.js';
+import { getFunctionDeclarationInfo } from './functions.js';
+/**
+ * Returns the sourcePath, jsPath, and package.json contents of the containing
+ * package for the given module path.
+ *
+ * This is a minimal subset of module information needed for constructing a
+ * Reference object for a module.
+ */
+export const getModuleInfo = (modulePath, analyzer, packageInfo = getPackageInfo(modulePath, analyzer)) => {
+    // The packageRoot for this module is needed for translating the source file
+    // path to a package relative path, and the packageName is needed for
+    // generating references to any symbols in this module.
+    const { rootDir, packageJson } = packageInfo;
+    const absJsPath = getJSPathFromSourcePath(modulePath, analyzer);
+    const jsPath = absJsPath !== undefined
+        ? absoluteToPackage(absJsPath, rootDir, analyzer.path.sep)
+        : 'not/implemented';
+    const sourcePath = absoluteToPackage(analyzer.path.normalize(modulePath), rootDir, analyzer.path.sep);
+    return {
+        jsPath,
+        sourcePath,
+        packageJson,
+    };
+};
+/**
+ * Returns an analyzer `Module` model for the given module path.
+ */
+export const getModule = (modulePath, analyzer, packageInfo = getPackageInfo(modulePath, analyzer)) => {
+    const { typescript: ts } = analyzer;
+    // Return cached module if we've parsed this sourceFile already and its
+    // dependencies haven't changed
+    const cachedModule = getAndValidateModuleFromCache(modulePath, analyzer);
+    if (cachedModule !== undefined) {
+        return cachedModule;
+    }
+    const sourceFile = analyzer.program.getSourceFile(analyzer.path.normalize(modulePath));
+    if (sourceFile === undefined) {
+        throw new Error(`Program did not contain a source file for ${modulePath}`);
+    }
+    const dependencies = new Set();
+    const declarationMap = new Map();
+    const exportMap = new Map();
+    const reexports = [];
+    const addDeclaration = (info) => {
+        const { name, node, factory, isExport } = info;
+        if (declarationMap.has(name)) {
+            analyzer.addDiagnostic(createDiagnostic({
+                typescript: ts,
+                node,
+                message: `Duplicate declaration '${name}'`,
+                category: ts.DiagnosticCategory.Error,
+            }));
+            return;
+        }
+        declarationMap.set(name, factory);
+        if (isExport) {
+            exportMap.set(name, name);
+        }
+    };
+    // Find and add models for declarations in the module
+    // TODO(kschaaf): Add Function and MixinDeclarations
+    for (const statement of sourceFile.statements) {
+        if (ts.isClassDeclaration(statement)) {
+            const decl = getClassDeclarationInfo(statement, analyzer);
+            if (decl !== undefined) {
+                addDeclaration(decl);
+            }
+            // Ignore non-implementation signatures of overloaded functions by
+            // checking for `statement.body`.
+        }
+        else if (ts.isFunctionDeclaration(statement) && statement.body) {
+            const decl = getFunctionDeclarationInfo(statement, analyzer);
+            if (decl !== undefined) {
+                addDeclaration(decl);
+            }
+        }
+        else if (ts.isVariableStatement(statement)) {
+            getVariableDeclarationInfo(statement, analyzer).forEach(addDeclaration);
+        }
+        else if (ts.isEnumDeclaration(statement)) {
+            addDeclaration(getEnumDeclarationInfo(statement, analyzer));
+        }
+        else if (ts.isExportDeclaration(statement) && !statement.isTypeOnly) {
+            const { exportClause, moduleSpecifier } = statement;
+            if (exportClause === undefined) {
+                // Case: `export * from 'foo';` The `exportClause` is undefined for
+                // wildcard exports. Add the re-exported module specifier to the
+                // `reexports` list, and we will add references to the exportMap lazily
+                // the first time exports are queried
+                if (moduleSpecifier === undefined) {
+                    analyzer.addDiagnostic(createDiagnostic({
+                        typescript: ts,
+                        node: statement,
+                        message: `Unexpected syntax: expected a wildcard export to always have a module specifier.`,
+                    }));
+                }
+                else {
+                    reexports.push(moduleSpecifier);
+                }
+            }
+            else {
+                // Case: `export {...}` and `export {...} from '...'`
+                // Add all of the exports in this export statement to the exportMap
+                getExportReferences(exportClause, moduleSpecifier, analyzer).forEach(({ exportName, decNameOrRef }) => exportMap.set(exportName, decNameOrRef));
+            }
+        }
+        else if (ts.isExportAssignment(statement)) {
+            addDeclaration(getExportAssignmentVariableDeclarationInfo(statement, analyzer));
+        }
+        else if (ts.isImportDeclaration(statement)) {
+            const path = getPathForModuleSpecifierExpression(statement.moduleSpecifier, analyzer);
+            if (path !== undefined) {
+                dependencies.add(path);
+            }
+        }
+    }
+    // Construct module and save in cache
+    const module = new Module({
+        ...getModuleInfo(modulePath, analyzer, packageInfo),
+        sourceFile,
+        declarationMap,
+        dependencies,
+        exportMap,
+        finalizeExports: () => finalizeExports(reexports, exportMap, analyzer),
+        ...parseModuleJSDocInfo(sourceFile, analyzer),
+    });
+    analyzer.moduleCache.set(analyzer.path.normalize(sourceFile.fileName), module);
+    return module;
+};
+/**
+ * For any re-exported modules (i.e. `export * from 'foo'`), add all of the
+ * exported names of the reexported module to the given exportMap, with
+ * References into that module.
+ */
+const finalizeExports = (reexportSpecifiers, exportMap, analyzer) => {
+    for (const moduleSpecifier of reexportSpecifiers) {
+        const path = getPathForModuleSpecifierExpression(moduleSpecifier, analyzer);
+        if (path === undefined) {
+            continue;
+        }
+        const module = getModule(path, analyzer);
+        for (const name of module.exportNames) {
+            exportMap.set(name, getImportReferenceForSpecifierExpression(moduleSpecifier, name, analyzer));
+        }
+    }
+};
+/**
+ * Returns a cached Module model for the given module path if it and all of its
+ * dependencies' models are still valid since the model was cached. If the
+ * cached module is out-of-date and needs to be re-created, this method returns
+ * undefined.
+ */
+const getAndValidateModuleFromCache = (modulePath, analyzer, seen = new Set([modulePath])) => {
+    const module = analyzer.moduleCache.get(modulePath);
+    // A cached module is only valid if the source file that was used has not
+    // changed in the current program, and if all of its dependencies are still
+    // valid
+    if (module !== undefined) {
+        if (module.sourceFile === analyzer.program.getSourceFile(modulePath) &&
+            depsAreValid(module, analyzer, seen)) {
+            return module;
+        }
+        analyzer.moduleCache.delete(modulePath);
+    }
+    return undefined;
+};
+/**
+ * Returns true if all dependencies of the module are still valid.
+ */
+const depsAreValid = (module, analyzer, seen) => Array.from(module.dependencies).every((path) => 
+// `seen` is initialized only once, at the entry point for the initial
+// call to `getAndValidateModuleFromCache`, and modulePaths are only added
+// to `seen` at  the deepest part of the recursion, in `depIsValid`
+// because of that, we can be confident that a module path which was 'seen'
+// has already been validated by `depIsValid` and can be safely skipped here.
+seen.has(path) || depIsValid(path, analyzer, seen));
+/**
+ * Returns true if the given dependency is valid, meaning that if it has a
+ * cached model, the model is still valid. Dependencies that don't yet have a
+ * cached model are considered valid.
+ */
+const depIsValid = (modulePath, analyzer, seen) => {
+    seen.add(modulePath);
+    if (analyzer.moduleCache.has(modulePath)) {
+        // If a dep has a model, it is valid only if its deps are valid
+        return Boolean(getAndValidateModuleFromCache(modulePath, analyzer, seen));
+    }
+    else {
+        // Deps that don't have a cached model are considered valid
+        return true;
+    }
+};
+/**
+ * For a given source file, return its associated JS file.
+ *
+ * For a JS source file, these will be the same thing. For a TS file, we use the
+ * TS API to determine where the associated JS will be output based on tsconfig
+ * settings.
+ */
+const getJSPathFromSourcePath = (sourcePath, analyzer) => {
+    sourcePath = analyzer.path.normalize(sourcePath);
+    // If the source file was already JS, just return that
+    if (sourcePath.endsWith('.js')) {
+        return sourcePath;
+    }
+    // TODO(kschaaf): If the source file was a declaration file, this means we're
+    // likely getting information about an externally imported package that had
+    // types. In this case, we'll need to update our logic to resolve the import
+    // specifier to the JS path (in addition to the source file path that we do
+    // today). Unfortunately, TS's specifier resolver always prefers a declaration
+    // file, and due to type roots and other tsconfig fancies, it's not
+    // straightforward to go from a declaration file to a source file. In order to
+    // properly implement this we'll probably need to bring our own node module
+    // resolver ala https://www.npmjs.com/package/resolve. That change should be
+    // done along with the custom-elements.json manifest work.
+    if (sourcePath.endsWith('.d.ts')) {
+        return undefined;
+    }
+    // Use the TS API to determine where the associated JS will be output based
+    // on tsconfig settings.
+    const outputPath = analyzer.typescript
+        .getOutputFileNames(analyzer.commandLine, sourcePath, false)
+        .filter((f) => f.endsWith('.js'))[0];
+    // TODO(kschaaf): this could happen if someone imported only a .d.ts file;
+    // we might need to handle this differently
+    if (outputPath === undefined) {
+        throw new Error(`Could not determine output filename for '${sourcePath}'`);
+    }
+    // The filename appears to come out of the ts API with
+    // unix separators; since sourcePath uses OS separators, normalize this so
+    // that all our model paths are OS-native
+    return analyzer.path.normalize(outputPath);
+};
+/**
+ * Resolves a module specifier expression node to an absolute path on disk.
+ */
+export const getPathForModuleSpecifierExpression = (specifierExpression, analyzer) => {
+    const specifier = getSpecifierString(specifierExpression);
+    return getPathForModuleSpecifier(specifier, specifierExpression, analyzer);
+};
+/**
+ * Resolve a module specifier to an absolute path on disk.
+ */
+export const getPathForModuleSpecifier = (specifier, location, analyzer) => {
+    const resolvedPath = analyzer.typescript.resolveModuleName(specifier, location.getSourceFile().fileName, analyzer.commandLine.options, analyzer.fs).resolvedModule?.resolvedFileName;
+    if (resolvedPath === undefined) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: location,
+            message: `Could not resolve specifier ${specifier} to filesystem path.`,
+            category: analyzer.typescript.DiagnosticCategory.Error,
+        }));
+        return undefined;
+    }
+    return analyzer.path.normalize(resolvedPath);
+};
+/**
+ * Returns the declaration for the named export of the given module path;
+ * note that if the given module re-exported a declaration from another
+ * module, references are followed to the concrete declaration, which is
+ * returned.
+ */
+export const getResolvedExportFromSourcePath = (modulePath, name, analyzer) => getModule(modulePath, analyzer)?.getResolvedExport(name);
+//# sourceMappingURL=modules.js.map

package/lib/javascript/modules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modules.js","sourceRoot":"","sources":["../../src/lib/javascript/modules.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2022 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/**\n * @fileoverview\n *\n * Utilities for analyzing ES modules\n */\n\nimport type ts from 'typescript';\nimport {\n  Module,\n  AnalyzerInterface,\n  PackageInfo,\n  Declaration,\n  DeclarationInfo,\n  ExportMap,\n  DeclarationMap,\n  ModuleInfo,\n  LocalNameOrReference,\n} from '../model.js';\nimport {getClassDeclarationInfo} from './classes.js';\nimport {\n  getExportAssignmentVariableDeclarationInfo,\n  getVariableDeclarationInfo,\n  getEnumDeclarationInfo,\n} from './variables.js';\nimport {AbsolutePath, PackagePath, absoluteToPackage} from '../paths.js';\nimport {getPackageInfo} from './packages.js';\nimport {createDiagnostic} from '../errors.js';\nimport {\n  getExportReferences,\n  getImportReferenceForSpecifierExpression,\n  getSpecifierString,\n} from '../references.js';\nimport {parseModuleJSDocInfo} from './jsdoc.js';\nimport {getFunctionDeclarationInfo} from './functions.js';\n\nexport type TypeScript = typeof ts;\n\n/**\n * Returns the sourcePath, jsPath, and package.json contents of the containing\n * package for the given module path.\n *\n * This is a minimal subset of module information needed for constructing a\n * Reference object for a module.\n */\nexport const getModuleInfo = (\n  modulePath: AbsolutePath,\n  analyzer: AnalyzerInterface,\n  packageInfo: PackageInfo = getPackageInfo(modulePath, analyzer)\n): ModuleInfo => {\n  // The packageRoot for this module is needed for translating the source file\n  // path to a package relative path, and the packageName is needed for\n  // generating references to any symbols in this module.\n  const {rootDir, packageJson} = packageInfo;\n  const absJsPath = getJSPathFromSourcePath(\n    modulePath as AbsolutePath,\n    analyzer\n  );\n  const jsPath =\n    absJsPath !== undefined\n      ? absoluteToPackage(absJsPath, rootDir, analyzer.path.sep)\n      : ('not/implemented' as PackagePath);\n  const sourcePath = absoluteToPackage(\n    analyzer.path.normalize(modulePath) as AbsolutePath,\n    rootDir,\n    analyzer.path.sep\n  );\n  return {\n    jsPath,\n    sourcePath,\n    packageJson,\n  };\n};\n\n/**\n * Returns an analyzer `Module` model for the given module path.\n */\nexport const getModule = (\n  modulePath: AbsolutePath,\n  analyzer: AnalyzerInterface,\n  packageInfo: PackageInfo = getPackageInfo(modulePath, analyzer)\n) => {\n  const {typescript: ts} = analyzer;\n  // Return cached module if we've parsed this sourceFile already and its\n  // dependencies haven't changed\n  const cachedModule = getAndValidateModuleFromCache(modulePath, analyzer);\n  if (cachedModule !== undefined) {\n    return cachedModule;\n  }\n  const sourceFile = analyzer.program.getSourceFile(\n    analyzer.path.normalize(modulePath)\n  );\n  if (sourceFile === undefined) {\n    throw new Error(`Program did not contain a source file for ${modulePath}`);\n  }\n\n  const dependencies = new Set<AbsolutePath>();\n  const declarationMap: DeclarationMap = new Map<string, () => Declaration>();\n  const exportMap: ExportMap = new Map<string, LocalNameOrReference>();\n  const reexports: ts.Expression[] = [];\n  const addDeclaration = (info: DeclarationInfo) => {\n    const {name, node, factory, isExport} = info;\n    if (declarationMap.has(name)) {\n      analyzer.addDiagnostic(\n        createDiagnostic({\n          typescript: ts,\n          node,\n          message: `Duplicate declaration '${name}'`,\n          category: ts.DiagnosticCategory.Error,\n        })\n      );\n      return;\n    }\n    declarationMap.set(name, factory);\n    if (isExport) {\n      exportMap.set(name, name);\n    }\n  };\n\n  // Find and add models for declarations in the module\n  // TODO(kschaaf): Add Function and MixinDeclarations\n  for (const statement of sourceFile.statements) {\n    if (ts.isClassDeclaration(statement)) {\n      const decl = getClassDeclarationInfo(statement, analyzer);\n      if (decl !== undefined) {\n        addDeclaration(decl);\n      }\n      // Ignore non-implementation signatures of overloaded functions by\n      // checking for `statement.body`.\n    } else if (ts.isFunctionDeclaration(statement) && statement.body) {\n      const decl = getFunctionDeclarationInfo(statement, analyzer);\n      if (decl !== undefined) {\n        addDeclaration(decl);\n      }\n    } else if (ts.isVariableStatement(statement)) {\n      getVariableDeclarationInfo(statement, analyzer).forEach(addDeclaration);\n    } else if (ts.isEnumDeclaration(statement)) {\n      addDeclaration(getEnumDeclarationInfo(statement, analyzer));\n    } else if (ts.isExportDeclaration(statement) && !statement.isTypeOnly) {\n      const {exportClause, moduleSpecifier} = statement;\n      if (exportClause === undefined) {\n        // Case: `export * from 'foo';` The `exportClause` is undefined for\n        // wildcard exports. Add the re-exported module specifier to the\n        // `reexports` list, and we will add references to the exportMap lazily\n        // the first time exports are queried\n        if (moduleSpecifier === undefined) {\n          analyzer.addDiagnostic(\n            createDiagnostic({\n              typescript: ts,\n              node: statement,\n              message: `Unexpected syntax: expected a wildcard export to always have a module specifier.`,\n            })\n          );\n        } else {\n          reexports.push(moduleSpecifier);\n        }\n      } else {\n        // Case: `export {...}` and `export {...} from '...'`\n        // Add all of the exports in this export statement to the exportMap\n        getExportReferences(exportClause, moduleSpecifier, analyzer).forEach(\n          ({exportName, decNameOrRef}) =>\n            exportMap.set(exportName, decNameOrRef)\n        );\n      }\n    } else if (ts.isExportAssignment(statement)) {\n      addDeclaration(\n        getExportAssignmentVariableDeclarationInfo(statement, analyzer)\n      );\n    } else if (ts.isImportDeclaration(statement)) {\n      const path = getPathForModuleSpecifierExpression(\n        statement.moduleSpecifier,\n        analyzer\n      );\n      if (path !== undefined) {\n        dependencies.add(path);\n      }\n    }\n  }\n  // Construct module and save in cache\n  const module = new Module({\n    ...getModuleInfo(modulePath, analyzer, packageInfo),\n    sourceFile,\n    declarationMap,\n    dependencies,\n    exportMap,\n    finalizeExports: () => finalizeExports(reexports, exportMap, analyzer),\n    ...parseModuleJSDocInfo(sourceFile, analyzer),\n  });\n  analyzer.moduleCache.set(\n    analyzer.path.normalize(sourceFile.fileName) as AbsolutePath,\n    module\n  );\n  return module;\n};\n\n/**\n * For any re-exported modules (i.e. `export * from 'foo'`), add all of the\n * exported names of the reexported module to the given exportMap, with\n * References into that module.\n */\nconst finalizeExports = (\n  reexportSpecifiers: ts.Expression[],\n  exportMap: ExportMap,\n  analyzer: AnalyzerInterface\n) => {\n  for (const moduleSpecifier of reexportSpecifiers) {\n    const path = getPathForModuleSpecifierExpression(moduleSpecifier, analyzer);\n    if (path === undefined) {\n      continue;\n    }\n    const module = getModule(path, analyzer);\n    for (const name of module.exportNames) {\n      exportMap.set(\n        name,\n        getImportReferenceForSpecifierExpression(\n          moduleSpecifier,\n          name,\n          analyzer\n        )\n      );\n    }\n  }\n};\n\n/**\n * Returns a cached Module model for the given module path if it and all of its\n * dependencies' models are still valid since the model was cached. If the\n * cached module is out-of-date and needs to be re-created, this method returns\n * undefined.\n */\nconst getAndValidateModuleFromCache = (\n  modulePath: AbsolutePath,\n  analyzer: AnalyzerInterface,\n  seen = new Set<AbsolutePath>([modulePath])\n): Module | undefined => {\n  const module = analyzer.moduleCache.get(modulePath);\n  // A cached module is only valid if the source file that was used has not\n  // changed in the current program, and if all of its dependencies are still\n  // valid\n  if (module !== undefined) {\n    if (\n      module.sourceFile === analyzer.program.getSourceFile(modulePath) &&\n      depsAreValid(module, analyzer, seen)\n    ) {\n      return module;\n    }\n    analyzer.moduleCache.delete(modulePath);\n  }\n  return undefined;\n};\n\n/**\n * Returns true if all dependencies of the module are still valid.\n */\nconst depsAreValid = (\n  module: Module,\n  analyzer: AnalyzerInterface,\n  seen: Set<AbsolutePath>\n): boolean =>\n  Array.from(module.dependencies).every(\n    (path) =>\n      // `seen` is initialized only once, at the entry point for the initial\n      // call to `getAndValidateModuleFromCache`, and modulePaths are only added\n      // to `seen` at  the deepest part of the recursion, in `depIsValid`\n      // because of that, we can be confident that a module path which was 'seen'\n      // has already been validated by `depIsValid` and can be safely skipped here.\n      seen.has(path) || depIsValid(path, analyzer, seen)\n  );\n\n/**\n * Returns true if the given dependency is valid, meaning that if it has a\n * cached model, the model is still valid. Dependencies that don't yet have a\n * cached model are considered valid.\n */\nconst depIsValid = (\n  modulePath: AbsolutePath,\n  analyzer: AnalyzerInterface,\n  seen: Set<AbsolutePath>\n) => {\n  seen.add(modulePath);\n  if (analyzer.moduleCache.has(modulePath)) {\n    // If a dep has a model, it is valid only if its deps are valid\n    return Boolean(getAndValidateModuleFromCache(modulePath, analyzer, seen));\n  } else {\n    // Deps that don't have a cached model are considered valid\n    return true;\n  }\n};\n\n/**\n * For a given source file, return its associated JS file.\n *\n * For a JS source file, these will be the same thing. For a TS file, we use the\n * TS API to determine where the associated JS will be output based on tsconfig\n * settings.\n */\nconst getJSPathFromSourcePath = (\n  sourcePath: AbsolutePath,\n  analyzer: AnalyzerInterface\n) => {\n  sourcePath = analyzer.path.normalize(sourcePath) as AbsolutePath;\n  // If the source file was already JS, just return that\n  if (sourcePath.endsWith('.js')) {\n    return sourcePath;\n  }\n  // TODO(kschaaf): If the source file was a declaration file, this means we're\n  // likely getting information about an externally imported package that had\n  // types. In this case, we'll need to update our logic to resolve the import\n  // specifier to the JS path (in addition to the source file path that we do\n  // today). Unfortunately, TS's specifier resolver always prefers a declaration\n  // file, and due to type roots and other tsconfig fancies, it's not\n  // straightforward to go from a declaration file to a source file. In order to\n  // properly implement this we'll probably need to bring our own node module\n  // resolver ala https://www.npmjs.com/package/resolve. That change should be\n  // done along with the custom-elements.json manifest work.\n  if (sourcePath.endsWith('.d.ts')) {\n    return undefined;\n  }\n  // Use the TS API to determine where the associated JS will be output based\n  // on tsconfig settings.\n  const outputPath = analyzer.typescript\n    .getOutputFileNames(analyzer.commandLine, sourcePath, false)\n    .filter((f) => f.endsWith('.js'))[0];\n  // TODO(kschaaf): this could happen if someone imported only a .d.ts file;\n  // we might need to handle this differently\n  if (outputPath === undefined) {\n    throw new Error(`Could not determine output filename for '${sourcePath}'`);\n  }\n  // The filename appears to come out of the ts API with\n  // unix separators; since sourcePath uses OS separators, normalize this so\n  // that all our model paths are OS-native\n  return analyzer.path.normalize(outputPath) as AbsolutePath;\n};\n\n/**\n * Resolves a module specifier expression node to an absolute path on disk.\n */\nexport const getPathForModuleSpecifierExpression = (\n  specifierExpression: ts.Expression,\n  analyzer: AnalyzerInterface\n): AbsolutePath | undefined => {\n  const specifier = getSpecifierString(specifierExpression);\n  return getPathForModuleSpecifier(specifier, specifierExpression, analyzer);\n};\n\n/**\n * Resolve a module specifier to an absolute path on disk.\n */\nexport const getPathForModuleSpecifier = (\n  specifier: string,\n  location: ts.Node,\n  analyzer: AnalyzerInterface\n): AbsolutePath | undefined => {\n  const resolvedPath = analyzer.typescript.resolveModuleName(\n    specifier,\n    location.getSourceFile().fileName,\n    analyzer.commandLine.options,\n    analyzer.fs\n  ).resolvedModule?.resolvedFileName;\n  if (resolvedPath === undefined) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: location,\n        message: `Could not resolve specifier ${specifier} to filesystem path.`,\n        category: analyzer.typescript.DiagnosticCategory.Error,\n      })\n    );\n    return undefined;\n  }\n  return analyzer.path.normalize(resolvedPath) as AbsolutePath;\n};\n\n/**\n * Returns the declaration for the named export of the given module path;\n * note that if the given module re-exported a declaration from another\n * module, references are followed to the concrete declaration, which is\n * returned.\n */\nexport const getResolvedExportFromSourcePath = (\n  modulePath: AbsolutePath,\n  name: string,\n  analyzer: AnalyzerInterface\n) => getModule(modulePath, analyzer)?.getResolvedExport(name);\n"]}

package/lib/javascript/packages.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { AnalyzerInterface, PackageInfo } from '../model.js';
+import { AbsolutePath } from '../paths.js';
+/**
+ * Starting from a given module path, searches up until the nearest package.json
+ * is found, returning that folder. If none is found, an error is thrown.
+ */
+export declare const getPackageRootForModulePath: (modulePath: AbsolutePath, analyzer: AnalyzerInterface) => AbsolutePath;
+/**
+ * Returns an analyzer `PackageInfo` model for the nearest package of the given
+ * path.
+ */
+export declare const getPackageInfo: (path: AbsolutePath, analyzer: AnalyzerInterface) => PackageInfo;
+//# sourceMappingURL=packages.d.ts.map

package/lib/javascript/packages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.d.ts","sourceRoot":"","sources":["../../src/lib/javascript/packages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,iBAAiB,EAAE,WAAW,EAAc,MAAM,aAAa,CAAC;AACxE,OAAO,EAAC,YAAY,EAAC,MAAM,aAAa,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,2BAA2B,GACtC,YAAY,YAAY,EACxB,UAAU,iBAAiB,KAC1B,YAYF,CAAC;AAkBF;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,YAAY,EAClB,UAAU,iBAAiB,gBAe5B,CAAC"}

package/lib/javascript/packages.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { PackageInfo } from '../model.js';
+/**
+ * Starting from a given module path, searches up until the nearest package.json
+ * is found, returning that folder. If none is found, an error is thrown.
+ */
+export const getPackageRootForModulePath = (modulePath, analyzer) => {
+    // TODO(kschaaf): Add caching & invalidation
+    const { fs, path } = analyzer;
+    let searchDir = modulePath;
+    const root = path.parse(searchDir).root;
+    while (!fs.fileExists(path.join(searchDir, 'package.json'))) {
+        if (searchDir === root) {
+            throw new Error(`No package.json found for module path ${modulePath}`);
+        }
+        searchDir = path.dirname(searchDir);
+    }
+    return searchDir;
+};
+/**
+ * Reads and parses a package.json file contained in the given folder.
+ */
+const getPackageJsonFromPackageRoot = (packageRoot, analyzer) => {
+    // TODO(kschaaf): Add caching & invalidation
+    const { fs, path } = analyzer;
+    const packageJson = fs.readFile(path.join(packageRoot, 'package.json'));
+    if (packageJson !== undefined) {
+        return JSON.parse(packageJson);
+    }
+    throw new Error(`No package.json found at ${packageRoot}`);
+};
+/**
+ * Returns an analyzer `PackageInfo` model for the nearest package of the given
+ * path.
+ */
+export const getPackageInfo = (path, analyzer) => {
+    const rootDir = getPackageRootForModulePath(path, analyzer);
+    const packageJson = getPackageJsonFromPackageRoot(rootDir, analyzer);
+    const { name } = packageJson;
+    if (name === undefined) {
+        throw new Error(`Expected package name in ${analyzer.path.join(rootDir, 'package.json')}`);
+    }
+    return new PackageInfo({
+        name,
+        rootDir: analyzer.path.normalize(rootDir),
+        packageJson,
+    });
+};
+//# sourceMappingURL=packages.js.map

package/lib/javascript/packages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packages.js","sourceRoot":"","sources":["../../src/lib/javascript/packages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAoB,WAAW,EAAc,MAAM,aAAa,CAAC;AAGxE;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,UAAwB,EACxB,QAA2B,EACb,EAAE;IAChB,4CAA4C;IAC5C,MAAM,EAAC,EAAE,EAAE,IAAI,EAAC,GAAG,QAAQ,CAAC;IAC5B,IAAI,SAAS,GAAG,UAAoB,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC;IACxC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC;QAC5D,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,yCAAyC,UAAU,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,SAAyB,CAAC;AACnC,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,6BAA6B,GAAG,CACpC,WAAyB,EACzB,QAA2B,EACd,EAAE;IACf,4CAA4C;IAC5C,MAAM,EAAC,EAAE,EAAE,IAAI,EAAC,GAAG,QAAQ,CAAC;IAC5B,MAAM,WAAW,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;IACxE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAgB,CAAC;IAChD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,4BAA4B,WAAW,EAAE,CAAC,CAAC;AAC7D,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,IAAkB,EAClB,QAA2B,EAC3B,EAAE;IACF,MAAM,OAAO,GAAG,2BAA2B,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,6BAA6B,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACrE,MAAM,EAAC,IAAI,EAAC,GAAG,WAAW,CAAC;IAC3B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,4BAA4B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,WAAW,CAAC;QACrB,IAAI;QACJ,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAiB;QACzD,WAAW;KACZ,CAAC,CAAC;AACL,CAAC,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2022 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\nimport {AnalyzerInterface, PackageInfo, PackageJson} from '../model.js';\nimport {AbsolutePath} from '../paths.js';\n\n/**\n * Starting from a given module path, searches up until the nearest package.json\n * is found, returning that folder. If none is found, an error is thrown.\n */\nexport const getPackageRootForModulePath = (\n  modulePath: AbsolutePath,\n  analyzer: AnalyzerInterface\n): AbsolutePath => {\n  // TODO(kschaaf): Add caching & invalidation\n  const {fs, path} = analyzer;\n  let searchDir = modulePath as string;\n  const root = path.parse(searchDir).root;\n  while (!fs.fileExists(path.join(searchDir, 'package.json'))) {\n    if (searchDir === root) {\n      throw new Error(`No package.json found for module path ${modulePath}`);\n    }\n    searchDir = path.dirname(searchDir);\n  }\n  return searchDir as AbsolutePath;\n};\n\n/**\n * Reads and parses a package.json file contained in the given folder.\n */\nconst getPackageJsonFromPackageRoot = (\n  packageRoot: AbsolutePath,\n  analyzer: AnalyzerInterface\n): PackageJson => {\n  // TODO(kschaaf): Add caching & invalidation\n  const {fs, path} = analyzer;\n  const packageJson = fs.readFile(path.join(packageRoot, 'package.json'));\n  if (packageJson !== undefined) {\n    return JSON.parse(packageJson) as PackageJson;\n  }\n  throw new Error(`No package.json found at ${packageRoot}`);\n};\n\n/**\n * Returns an analyzer `PackageInfo` model for the nearest package of the given\n * path.\n */\nexport const getPackageInfo = (\n  path: AbsolutePath,\n  analyzer: AnalyzerInterface\n) => {\n  const rootDir = getPackageRootForModulePath(path, analyzer);\n  const packageJson = getPackageJsonFromPackageRoot(rootDir, analyzer);\n  const {name} = packageJson;\n  if (name === undefined) {\n    throw new Error(\n      `Expected package name in ${analyzer.path.join(rootDir, 'package.json')}`\n    );\n  }\n  return new PackageInfo({\n    name,\n    rootDir: analyzer.path.normalize(rootDir) as AbsolutePath,\n    packageJson,\n  });\n};\n"]}

package/lib/javascript/variables.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * @fileoverview
+ *
+ * Utilities for analyzing variable declarations
+ */
+import type ts from 'typescript';
+import { VariableDeclaration, AnalyzerInterface, DeclarationInfo } from '../model.js';
+export type TypeScript = typeof ts;
+/**
+ * Returns name and model factories for all variable
+ * declarations in a variable statement.
+ */
+export declare const getVariableDeclarationInfo: (statement: ts.VariableStatement, analyzer: AnalyzerInterface) => DeclarationInfo[];
+/**
+ * Returns declaration info & factory for a default export assignment.
+ */
+export declare const getExportAssignmentVariableDeclarationInfo: (exportAssignment: ts.ExportAssignment, analyzer: AnalyzerInterface) => DeclarationInfo;
+export declare const getEnumDeclarationInfo: (dec: ts.EnumDeclaration, analyzer: AnalyzerInterface) => {
+    name: string;
+    node: ts.EnumDeclaration;
+    factory: () => VariableDeclaration;
+    isExport: boolean;
+};
+//# sourceMappingURL=variables.d.ts.map

package/lib/javascript/variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../src/lib/javascript/variables.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EAEhB,MAAM,aAAa,CAAC;AASrB,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAC;AA8DnC;;;GAGG;AACH,eAAO,MAAM,0BAA0B,GACrC,WAAW,EAAE,CAAC,iBAAiB,EAC/B,UAAU,iBAAiB,KAC1B,eAAe,EAQjB,CAAC;AA0DF;;GAEG;AACH,eAAO,MAAM,0CAA0C,GACrD,kBAAkB,EAAE,CAAC,gBAAgB,EACrC,UAAU,iBAAiB,KAC1B,eAQF,CAAC;AAsBF,eAAO,MAAM,sBAAsB,GACjC,KAAK,EAAE,CAAC,eAAe,EACvB,UAAU,iBAAiB;;;;;CAQ5B,CAAC"}

package/lib/javascript/variables.js

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { VariableDeclaration, } from '../model.js';
+import { hasExportModifier } from '../utils.js';
+import { getTypeForNode } from '../types.js';
+import { parseNodeJSDocInfo } from './jsdoc.js';
+import { getFunctionDeclaration } from './functions.js';
+import { getClassDeclaration, maybeGetAppliedMixin } from './classes.js';
+import { createDiagnostic } from '../errors.js';
+import { DiagnosticCode } from '../diagnostic-code.js';
+/**
+ * Returns an analyzer `VariableDeclaration` model for the given
+ * ts.Identifier within a potentially nested ts.VariableDeclaration.
+ */
+const getVariableDeclaration = (statement, dec, name, analyzer) => {
+    const { typescript: ts } = analyzer;
+    // For const variable declarations initialized to functions or classes, we
+    // treat these as FunctionDeclaration and ClassDeclaration, respectively since
+    // they are (mostly) unobservably different to the module consumer and we can
+    // give better docs this way
+    if (ts.isVariableDeclaration(dec) &&
+        Boolean(statement.declarationList.flags & ts.NodeFlags.Const) &&
+        dec.initializer !== undefined) {
+        const { initializer } = dec;
+        if (ts.isArrowFunction(initializer) ||
+            ts.isFunctionExpression(initializer)) {
+            return getFunctionDeclaration(initializer, name.getText(), analyzer, statement);
+        }
+        else if (ts.isClassExpression(initializer)) {
+            return getClassDeclaration(initializer, name.getText(), analyzer, statement);
+        }
+        else {
+            // This supports const assignments of mixins applied to classes, ala:
+            // `export const MyClassWithSomeMixin = SomeMixin(MyClass);`
+            const classDec = maybeGetAppliedMixin(initializer, name, analyzer);
+            if (classDec !== undefined) {
+                return classDec;
+            }
+        }
+    }
+    return new VariableDeclaration({
+        name: name.text,
+        node: dec,
+        type: getTypeForNode(name, analyzer),
+        ...parseNodeJSDocInfo(statement, analyzer),
+    });
+};
+/**
+ * Returns name and model factories for all variable
+ * declarations in a variable statement.
+ */
+export const getVariableDeclarationInfo = (statement, analyzer) => {
+    const isExport = hasExportModifier(analyzer.typescript, statement);
+    const { declarationList } = statement;
+    return declarationList.declarations
+        .map((d) => getVariableDeclarationInfoList(statement, d, d.name, isExport, analyzer))
+        .flat();
+};
+/**
+ * For a given `VariableName` (which might be a simple identifier or a
+ * destructuring pattern which contains more identifiers), return an array of
+ * tuples of name and factory for each declaration.
+ */
+const getVariableDeclarationInfoList = (statement, dec, name, isExport, analyzer) => {
+    const { typescript: ts } = analyzer;
+    if (ts.isIdentifier(name)) {
+        return [
+            {
+                name: name.text,
+                node: name,
+                factory: () => getVariableDeclaration(statement, dec, name, analyzer),
+                isExport,
+            },
+        ];
+    }
+    else if (
+    // Recurse into the elements of an array/object destructuring variable
+    // declaration to find the identifiers
+    ts.isObjectBindingPattern(name) ||
+        ts.isArrayBindingPattern(name)) {
+        const els = name.elements.filter((el) => ts.isBindingElement(el));
+        return els
+            .map((el) => getVariableDeclarationInfoList(statement, dec, el.name, isExport, analyzer))
+            .flat();
+    }
+    else {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: ts,
+            node: dec,
+            message: `Expected declaration name to either be an identifier or a destructuring`,
+            category: ts.DiagnosticCategory.Warning,
+            code: DiagnosticCode.UNSUPPORTED,
+        }));
+        return [];
+    }
+};
+/**
+ * Returns declaration info & factory for a default export assignment.
+ */
+export const getExportAssignmentVariableDeclarationInfo = (exportAssignment, analyzer) => {
+    return {
+        name: 'default',
+        node: exportAssignment,
+        factory: () => getExportAssignmentVariableDeclaration(exportAssignment, analyzer),
+        isExport: true,
+    };
+};
+/**
+ * Returns an analyzer `VariableDeclaration` model for the given default
+ * ts.ExportAssignment, handling the case of: `export const 'some expression'`;
+ *
+ * Note that even though this technically isn't a VariableDeclaration in
+ * TS, we model it as one since it could unobservably be implemented as
+ * `const varDec = 'some expression'; export {varDec as default} `
+ */
+const getExportAssignmentVariableDeclaration = (exportAssignment, analyzer) => {
+    return new VariableDeclaration({
+        name: 'default',
+        node: exportAssignment,
+        type: getTypeForNode(exportAssignment.expression, analyzer),
+        ...parseNodeJSDocInfo(exportAssignment, analyzer),
+    });
+};
+export const getEnumDeclarationInfo = (dec, analyzer) => {
+    return {
+        name: dec.name.text,
+        node: dec,
+        factory: () => getEnumDeclaration(dec, analyzer),
+        isExport: hasExportModifier(analyzer.typescript, dec),
+    };
+};
+const getEnumDeclaration = (dec, analyzer) => {
+    return new VariableDeclaration({
+        name: dec.name.text,
+        node: dec,
+        type: getTypeForNode(dec.name, analyzer),
+        ...parseNodeJSDocInfo(dec, analyzer),
+    });
+};
+//# sourceMappingURL=variables.js.map

package/lib/javascript/variables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.js","sourceRoot":"","sources":["../../src/lib/javascript/variables.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2022 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/**\n * @fileoverview\n *\n * Utilities for analyzing variable declarations\n */\n\nimport type ts from 'typescript';\nimport {\n  VariableDeclaration,\n  AnalyzerInterface,\n  DeclarationInfo,\n  Declaration,\n} from '../model.js';\nimport {hasExportModifier} from '../utils.js';\nimport {getTypeForNode} from '../types.js';\nimport {parseNodeJSDocInfo} from './jsdoc.js';\nimport {getFunctionDeclaration} from './functions.js';\nimport {getClassDeclaration, maybeGetAppliedMixin} from './classes.js';\nimport {createDiagnostic} from '../errors.js';\nimport {DiagnosticCode} from '../diagnostic-code.js';\n\nexport type TypeScript = typeof ts;\n\ntype VariableName =\n  | ts.Identifier\n  | ts.ObjectBindingPattern\n  | ts.ArrayBindingPattern;\n\n/**\n * Returns an analyzer `VariableDeclaration` model for the given\n * ts.Identifier within a potentially nested ts.VariableDeclaration.\n */\nconst getVariableDeclaration = (\n  statement: ts.VariableStatement,\n  dec: ts.VariableDeclaration,\n  name: ts.Identifier,\n  analyzer: AnalyzerInterface\n): Declaration => {\n  const {typescript: ts} = analyzer;\n  // For const variable declarations initialized to functions or classes, we\n  // treat these as FunctionDeclaration and ClassDeclaration, respectively since\n  // they are (mostly) unobservably different to the module consumer and we can\n  // give better docs this way\n  if (\n    ts.isVariableDeclaration(dec) &&\n    Boolean(statement.declarationList.flags & ts.NodeFlags.Const) &&\n    dec.initializer !== undefined\n  ) {\n    const {initializer} = dec;\n    if (\n      ts.isArrowFunction(initializer) ||\n      ts.isFunctionExpression(initializer)\n    ) {\n      return getFunctionDeclaration(\n        initializer,\n        name.getText(),\n        analyzer,\n        statement\n      );\n    } else if (ts.isClassExpression(initializer)) {\n      return getClassDeclaration(\n        initializer,\n        name.getText(),\n        analyzer,\n        statement\n      );\n    } else {\n      // This supports const assignments of mixins applied to classes, ala:\n      // `export const MyClassWithSomeMixin = SomeMixin(MyClass);`\n      const classDec = maybeGetAppliedMixin(initializer, name, analyzer);\n      if (classDec !== undefined) {\n        return classDec;\n      }\n    }\n  }\n  return new VariableDeclaration({\n    name: name.text,\n    node: dec,\n    type: getTypeForNode(name, analyzer),\n    ...parseNodeJSDocInfo(statement, analyzer),\n  });\n};\n\n/**\n * Returns name and model factories for all variable\n * declarations in a variable statement.\n */\nexport const getVariableDeclarationInfo = (\n  statement: ts.VariableStatement,\n  analyzer: AnalyzerInterface\n): DeclarationInfo[] => {\n  const isExport = hasExportModifier(analyzer.typescript, statement);\n  const {declarationList} = statement;\n  return declarationList.declarations\n    .map((d) =>\n      getVariableDeclarationInfoList(statement, d, d.name, isExport, analyzer)\n    )\n    .flat();\n};\n\n/**\n * For a given `VariableName` (which might be a simple identifier or a\n * destructuring pattern which contains more identifiers), return an array of\n * tuples of name and factory for each declaration.\n */\nconst getVariableDeclarationInfoList = (\n  statement: ts.VariableStatement,\n  dec: ts.VariableDeclaration,\n  name: VariableName,\n  isExport: boolean,\n  analyzer: AnalyzerInterface\n): DeclarationInfo[] => {\n  const {typescript: ts} = analyzer;\n  if (ts.isIdentifier(name)) {\n    return [\n      {\n        name: name.text,\n        node: name,\n        factory: () => getVariableDeclaration(statement, dec, name, analyzer),\n        isExport,\n      },\n    ];\n  } else if (\n    // Recurse into the elements of an array/object destructuring variable\n    // declaration to find the identifiers\n    ts.isObjectBindingPattern(name) ||\n    ts.isArrayBindingPattern(name)\n  ) {\n    const els = name.elements.filter((el) =>\n      ts.isBindingElement(el)\n    ) as ts.BindingElement[];\n    return els\n      .map((el) =>\n        getVariableDeclarationInfoList(\n          statement,\n          dec,\n          el.name,\n          isExport,\n          analyzer\n        )\n      )\n      .flat();\n  } else {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: ts,\n        node: dec,\n        message: `Expected declaration name to either be an identifier or a destructuring`,\n        category: ts.DiagnosticCategory.Warning,\n        code: DiagnosticCode.UNSUPPORTED,\n      })\n    );\n    return [];\n  }\n};\n\n/**\n * Returns declaration info & factory for a default export assignment.\n */\nexport const getExportAssignmentVariableDeclarationInfo = (\n  exportAssignment: ts.ExportAssignment,\n  analyzer: AnalyzerInterface\n): DeclarationInfo => {\n  return {\n    name: 'default',\n    node: exportAssignment,\n    factory: () =>\n      getExportAssignmentVariableDeclaration(exportAssignment, analyzer),\n    isExport: true,\n  };\n};\n\n/**\n * Returns an analyzer `VariableDeclaration` model for the given default\n * ts.ExportAssignment, handling the case of: `export const 'some expression'`;\n *\n * Note that even though this technically isn't a VariableDeclaration in\n * TS, we model it as one since it could unobservably be implemented as\n * `const varDec = 'some expression'; export {varDec as default} `\n */\nconst getExportAssignmentVariableDeclaration = (\n  exportAssignment: ts.ExportAssignment,\n  analyzer: AnalyzerInterface\n): VariableDeclaration => {\n  return new VariableDeclaration({\n    name: 'default',\n    node: exportAssignment,\n    type: getTypeForNode(exportAssignment.expression, analyzer),\n    ...parseNodeJSDocInfo(exportAssignment, analyzer),\n  });\n};\n\nexport const getEnumDeclarationInfo = (\n  dec: ts.EnumDeclaration,\n  analyzer: AnalyzerInterface\n) => {\n  return {\n    name: dec.name.text,\n    node: dec,\n    factory: () => getEnumDeclaration(dec, analyzer),\n    isExport: hasExportModifier(analyzer.typescript, dec),\n  };\n};\n\nconst getEnumDeclaration = (\n  dec: ts.EnumDeclaration,\n  analyzer: AnalyzerInterface\n) => {\n  return new VariableDeclaration({\n    name: dec.name.text,\n    node: dec,\n    type: getTypeForNode(dec.name, analyzer),\n    ...parseNodeJSDocInfo(dec, analyzer),\n  });\n};\n"]}

package/lib/lit/decorators.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * @fileoverview
+ *
+ * Utilities for analyzing ReactiveElement decorators.
+ */
+import type ts from 'typescript';
+export type TypeScript = typeof ts;
+export declare const isCustomElementDecorator: (ts: TypeScript, decorator: ts.Decorator) => decorator is CustomElementDecorator;
+/**
+ * A narrower type for ts.Decorator that represents the shape of an analyzable
+ * `@customElement('x')` callsite.
+ */
+export interface CustomElementDecorator extends ts.Decorator {
+    readonly expression: ts.CallExpression;
+}
+export declare const getPropertyDecorator: (ts: TypeScript, declaration: ts.PropertyDeclaration) => PropertyDecorator | undefined;
+/**
+ * A narrower type for ts.Decorator that represents the shape of an analyzable
+ * `@customElement('x')` callsite.
+ */
+interface PropertyDecorator extends ts.Decorator {
+    readonly expression: ts.CallExpression;
+}
+/**
+ * Gets the property options object from a `@property()` decorator callsite.
+ *
+ * Only works with an object literal passed as the first argument.
+ */
+export declare const getPropertyOptions: (ts: TypeScript, decorator: PropertyDecorator) => ts.ObjectLiteralExpression | undefined;
+export {};
+//# sourceMappingURL=decorators.d.ts.map