@oicl-lit/analyzer 0.14.1

package/lib/javascript/classes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * @fileoverview
+ *
+ * Utilities for analyzing class declarations
+ */
+import type ts from 'typescript';
+import { ClassDeclaration, AnalyzerInterface, DeclarationInfo, ClassHeritage, Reference, ClassField, ClassMethod } from '../model.js';
+export type TypeScript = typeof ts;
+/**
+ * Returns an analyzer `ClassDeclaration` model for the given
+ * ts.ClassLikeDeclaration.
+ *
+ * Note, the `docNode` may differ from the `declaration` in the case of a const
+ * assignment to a class expression, as the JSDoc will be attached to the
+ * VariableStatement rather than the class-like expression.
+ */
+export declare const getClassDeclaration: (declaration: ts.ClassLikeDeclaration, name: string, analyzer: AnalyzerInterface, docNode?: ts.Node, isMixinClass?: boolean) => ClassDeclaration;
+/**
+ * Returns the `fields` and `methods` of a class.
+ */
+export declare const getClassMembers: (declaration: ts.ClassLikeDeclaration, analyzer: AnalyzerInterface) => {
+    fieldMap: Map<string, ClassField>;
+    staticFieldMap: Map<string, ClassField>;
+    methodMap: Map<string, ClassMethod>;
+    staticMethodMap: Map<string, ClassMethod>;
+};
+/**
+ * Returns name and model factory for a class declaration.
+ */
+export declare const getClassDeclarationInfo: (declaration: ts.ClassDeclaration, analyzer: AnalyzerInterface) => DeclarationInfo | undefined;
+/**
+ * Returns the superClass and any applied mixins for a given class declaration.
+ */
+export declare const getHeritage: (declaration: ts.ClassLikeDeclarationBase, analyzer: AnalyzerInterface, isMixinClass?: boolean) => ClassHeritage;
+export declare const getHeritageFromExpression: (expression: ts.Expression, analyzer: AnalyzerInterface, isMixinClass?: boolean) => ClassHeritage;
+export declare const getSuperClassAndMixins: (expression: ts.Expression, foundMixins: Reference[], analyzer: AnalyzerInterface) => Reference | undefined;
+export declare const isConstructorFieldInitializer: (expression: ts.Expression, typescript: typeof ts) => expression is ConstructorFieldInitializer;
+type ConstructorFieldInitializer = ts.AssignmentExpression<ts.EqualsToken> & {
+    left: ts.PropertyAccessExpression & {
+        expression: ts.ThisExpression;
+    };
+};
+export declare const maybeGetAppliedMixin: (expression: ts.Expression, identifier: ts.Identifier, analyzer: AnalyzerInterface) => ClassDeclaration | undefined;
+export {};
+//# sourceMappingURL=classes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classes.d.ts","sourceRoot":"","sources":["../../src/lib/javascript/classes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAGjC,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,SAAS,EACT,UAAU,EACV,WAAW,EAEZ,MAAM,aAAa,CAAC;AAoBrB,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,EAAE,CAAC,oBAAoB,EACpC,MAAM,MAAM,EACZ,UAAU,iBAAiB,EAC3B,UAAU,EAAE,CAAC,IAAI,EACjB,eAAe,OAAO,qBAevB,CAAC;AAwBF;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,aAAa,EAAE,CAAC,oBAAoB,EACpC,UAAU,iBAAiB;;;;;CAsH5B,CAAC;AAuCF;;GAEG;AACH,eAAO,MAAM,uBAAuB,GAClC,aAAa,EAAE,CAAC,gBAAgB,EAChC,UAAU,iBAAiB,KAC1B,eAAe,GAAG,SAWpB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GACtB,aAAa,EAAE,CAAC,wBAAwB,EACxC,UAAU,iBAAiB,EAC3B,eAAe,OAAO,KACrB,aA0BF,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,YAAY,EAAE,CAAC,UAAU,EACzB,UAAU,iBAAiB,EAC3B,eAAe,OAAO,KACrB,aAOF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,YAAY,EAAE,CAAC,UAAU,EACzB,aAAa,SAAS,EAAE,EACxB,UAAU,iBAAiB,KAC1B,SAAS,GAAG,SA4Dd,CAAC;AAEF,eAAO,MAAM,6BAA6B,GACxC,YAAY,EAAE,CAAC,UAAU,EACzB,YAAY,OAAO,EAAE,KACpB,UAAU,IAAI,2BAOhB,CAAC;AAEF,KAAK,2BAA2B,GAAG,EAAE,CAAC,oBAAoB,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG;IAC3E,IAAI,EAAE,EAAE,CAAC,wBAAwB,GAAG;QAAC,UAAU,EAAE,EAAE,CAAC,cAAc,CAAA;KAAC,CAAC;CACrE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,YAAY,EAAE,CAAC,UAAU,EACzB,YAAY,EAAE,CAAC,UAAU,EACzB,UAAU,iBAAiB,KAC1B,gBAAgB,GAAG,SAwBrB,CAAC"}

package/lib/javascript/classes.js

@@ -0,0 +1,307 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { DiagnosticCode } from '../diagnostic-code.js';
+import { createDiagnostic } from '../errors.js';
+import { ClassDeclaration, ClassField, ClassMethod, MixinDeclaration, } from '../model.js';
+import { isLitElementSubclass, getLitElementDeclaration, } from '../lit-element/lit-element.js';
+import { getReferenceForIdentifier } from '../references.js';
+import { parseNodeJSDocInfo } from './jsdoc.js';
+import { hasDefaultModifier, hasStaticModifier, hasExportModifier, getPrivacy, } from '../utils.js';
+import { getFunctionLikeInfo } from './functions.js';
+import { getTypeForNode } from '../types.js';
+import { isCustomElementSubclass, getCustomElementDeclaration, } from '../custom-elements/custom-elements.js';
+/**
+ * Returns an analyzer `ClassDeclaration` model for the given
+ * ts.ClassLikeDeclaration.
+ *
+ * Note, the `docNode` may differ from the `declaration` in the case of a const
+ * assignment to a class expression, as the JSDoc will be attached to the
+ * VariableStatement rather than the class-like expression.
+ */
+export const getClassDeclaration = (declaration, name, analyzer, docNode, isMixinClass) => {
+    if (isLitElementSubclass(declaration, analyzer)) {
+        return getLitElementDeclaration(declaration, analyzer, isMixinClass);
+    }
+    if (isCustomElementSubclass(declaration, analyzer)) {
+        return getCustomElementDeclaration(declaration, analyzer, isMixinClass);
+    }
+    return new ClassDeclaration({
+        name,
+        node: declaration,
+        getHeritage: () => getHeritage(declaration, analyzer, isMixinClass),
+        ...parseNodeJSDocInfo(docNode ?? declaration, analyzer),
+        ...getClassMembers(declaration, analyzer),
+    });
+};
+const getIsReadonlyForNode = (node, analyzer) => {
+    const { typescript } = analyzer;
+    if (typescript.isPropertyDeclaration(node)) {
+        return (node.modifiers?.some((mod) => typescript.isReadonlyKeywordOrPlusOrMinusToken(mod)) ||
+            typescript
+                .getJSDocTags(node)
+                .some((tag) => tag.tagName.text === 'readonly'));
+    }
+    else if (typescript.isStatement(node)) {
+        return typescript
+            .getJSDocTags(node)
+            .some((tag) => tag.tagName.text === 'readonly');
+    }
+    return false;
+};
+/**
+ * Returns the `fields` and `methods` of a class.
+ */
+export const getClassMembers = (declaration, analyzer) => {
+    const { typescript } = analyzer;
+    const fieldMap = new Map();
+    const staticFieldMap = new Map();
+    const methodMap = new Map();
+    const staticMethodMap = new Map();
+    const accessors = new Map();
+    declaration.members.forEach((member) => {
+        // Ignore non-implementation signatures of overloaded methods by checking
+        // for `node.body`.
+        if (typescript.isConstructorDeclaration(member) && member.body) {
+            // TODO(bennypowers): We probably want to see if this matches what TypeScript considers a field initialization.
+            // Maybe instead of iterating through the constructor statements, we walk the body looking for any
+            // assignment expression so that we get ones inside of if statements, in parenthesized expressions, etc.
+            //
+            // Also, this doesn't cover destructuring assignment.
+            //
+            // This is ok for now because these are rare ways to "declare" a field,
+            // especially in web components where you shouldn't have constructor parameters.
+            member.body.statements.forEach((statement) => {
+                if (typescript.isExpressionStatement(statement) &&
+                    isConstructorFieldInitializer(statement.expression, typescript)) {
+                    const name = statement.expression.left.name.getText();
+                    fieldMap.set(name, new ClassField({
+                        name,
+                        type: getTypeForNode(statement.expression.right, analyzer),
+                        privacy: getPrivacy(typescript, statement),
+                        readonly: getIsReadonlyForNode(statement, analyzer),
+                        node: statement.expression,
+                    }));
+                }
+            });
+        }
+        else if (typescript.isMethodDeclaration(member) && member.body) {
+            const info = getMemberInfo(typescript, member);
+            const name = member.name.getText();
+            (info.static ? staticMethodMap : methodMap).set(name, new ClassMethod({
+                ...info,
+                ...getFunctionLikeInfo(member, name, analyzer),
+                ...parseNodeJSDocInfo(member, analyzer),
+                node: member,
+            }));
+        }
+        else if (typescript.isPropertyDeclaration(member)) {
+            if (!typescript.isIdentifier(member.name) &&
+                !typescript.isPrivateIdentifier(member.name)) {
+                analyzer.addDiagnostic(createDiagnostic({
+                    typescript,
+                    node: member,
+                    message: '@lit-labs/analyzer only supports analyzing class properties ' +
+                        'named with plain identifiers, or private class fields. This ' +
+                        'property was ignored: ' +
+                        member.name.getText(),
+                    category: typescript.DiagnosticCategory.Warning,
+                    code: DiagnosticCode.UNSUPPORTED,
+                }));
+                return;
+            }
+            const info = getMemberInfo(typescript, member);
+            (info.static ? staticFieldMap : fieldMap).set(member.name.getText(), new ClassField({
+                ...info,
+                default: member.initializer?.getText(),
+                type: getTypeForNode(member, analyzer),
+                ...parseNodeJSDocInfo(member, analyzer),
+                readonly: getIsReadonlyForNode(member, analyzer),
+                node: member,
+            }));
+        }
+        else if (typescript.isAccessor(member)) {
+            const name = member.name.getText();
+            const _accessors = accessors.get(name) ?? {};
+            if (typescript.isGetAccessor(member))
+                _accessors.get = member;
+            else if (typescript.isSetAccessor(member))
+                _accessors.set = member;
+            accessors.set(name, _accessors);
+        }
+    });
+    for (const [name, { get, set }] of accessors) {
+        if (get ?? set) {
+            fieldMap.set(name, new ClassField({
+                name,
+                type: getTypeForNode((get ?? set), analyzer),
+                privacy: getPrivacy(typescript, (get ?? set)),
+                readonly: !!get && !set,
+                // TODO(bennypowers): derive from getter?
+                // default: ???
+                // TODO(bennypowers): reflect, etc?
+                node: (set ?? get),
+            }));
+        }
+    }
+    return {
+        fieldMap,
+        staticFieldMap,
+        methodMap,
+        staticMethodMap,
+    };
+};
+const getMemberInfo = (typescript, node) => {
+    return {
+        name: node.name.getText(),
+        static: hasStaticModifier(typescript, node),
+        privacy: getPrivacy(typescript, node),
+    };
+};
+/**
+ * Returns the name of a class declaration.
+ */
+const getClassDeclarationName = (declaration, analyzer) => {
+    const name = declaration.name?.text ??
+        // The only time a class declaration will not have a name is when it is
+        // a default export, aka `export default class { }`
+        (hasDefaultModifier(analyzer.typescript, declaration)
+            ? 'default'
+            : undefined);
+    if (name === undefined) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: declaration,
+            message: `Illegal syntax: a class declaration must either have a name or be a default export`,
+        }));
+    }
+    return name;
+};
+/**
+ * Returns name and model factory for a class declaration.
+ */
+export const getClassDeclarationInfo = (declaration, analyzer) => {
+    const name = getClassDeclarationName(declaration, analyzer);
+    if (name === undefined) {
+        return undefined;
+    }
+    return {
+        name,
+        node: declaration,
+        factory: () => getClassDeclaration(declaration, name, analyzer),
+        isExport: hasExportModifier(analyzer.typescript, declaration),
+    };
+};
+/**
+ * Returns the superClass and any applied mixins for a given class declaration.
+ */
+export const getHeritage = (declaration, analyzer, isMixinClass) => {
+    const extendsClause = declaration.heritageClauses?.find((c) => c.token === analyzer.typescript.SyntaxKind.ExtendsKeyword);
+    if (extendsClause !== undefined) {
+        if (extendsClause.types.length === 1) {
+            return getHeritageFromExpression(extendsClause.types[0].expression, analyzer, isMixinClass);
+        }
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: extendsClause,
+            message: 'Illegal syntax: did not expect extends clause to have multiple types',
+        }));
+    }
+    // No extends clause; return empty heritage
+    return {
+        mixins: [],
+        superClass: undefined,
+    };
+};
+export const getHeritageFromExpression = (expression, analyzer, isMixinClass) => {
+    const mixins = [];
+    const superClass = getSuperClassAndMixins(expression, mixins, analyzer);
+    return {
+        superClass: isMixinClass ? undefined : superClass,
+        mixins,
+    };
+};
+export const getSuperClassAndMixins = (expression, foundMixins, analyzer) => {
+    // TODO(kschaaf) Could add support for inline class expressions here as well
+    if (analyzer.typescript.isIdentifier(expression)) {
+        return getReferenceForIdentifier(expression, analyzer);
+    }
+    else if (analyzer.typescript.isCallExpression(expression) &&
+        analyzer.typescript.isIdentifier(expression.expression)) {
+        // FYI we purposely restrict to identifiers since we represent mixins
+        // as references. If we want to support complex expressions in future,
+        // we will need to rework that in the model.
+        const mixinRef = getReferenceForIdentifier(expression.expression, analyzer);
+        // We need to eagerly dereference a mixin ref to know what argument the
+        // super class is passed into
+        let mixin;
+        try {
+            mixin = mixinRef?.dereference(MixinDeclaration);
+        }
+        catch (_err) {
+            // It wasn't a MixinDeclaration for whatever reason
+            mixin = undefined;
+        }
+        // TODO (43081j): consider supporting external mixins properly at some point
+        // An external mixin is one which we discovered via analysis (e.g. CEM)
+        // but don't have a reference to in sources. In future, we should support
+        // those as it is likely we will pull most dependencies from manifest
+        // analysis rather than source.
+        // See issue #4492
+        if (mixinRef === undefined || mixin === undefined) {
+            analyzer.addDiagnostic(createDiagnostic({
+                typescript: analyzer.typescript,
+                node: expression,
+                message: `This is presumed to be a mixin but it could not be found ` +
+                    `in the current project. Mixins imported from outside the ` +
+                    `project are not yet supported ` +
+                    `(see https://github.com/lit/lit/issues/4492).`,
+                code: DiagnosticCode.UNSUPPORTED,
+                category: analyzer.typescript.DiagnosticCategory.Warning,
+            }));
+            return undefined;
+        }
+        foundMixins.push(mixinRef);
+        const superArg = expression.arguments[mixin.superClassArgIndex];
+        const superClass = getSuperClassAndMixins(superArg, foundMixins, analyzer);
+        return superClass;
+    }
+    analyzer.addDiagnostic(createDiagnostic({
+        typescript: analyzer.typescript,
+        node: expression,
+        message: `Expected expression to be a concrete superclass or mixin.`,
+        code: DiagnosticCode.UNSUPPORTED,
+        category: analyzer.typescript.DiagnosticCategory.Warning,
+    }));
+    return undefined;
+};
+export const isConstructorFieldInitializer = (expression, typescript) => {
+    return (typescript.isBinaryExpression(expression) &&
+        expression.operatorToken.kind === typescript.SyntaxKind.EqualsToken &&
+        typescript.isPropertyAccessExpression(expression.left) &&
+        expression.left.expression.kind === typescript.SyntaxKind.ThisKeyword);
+};
+export const maybeGetAppliedMixin = (expression, identifier, analyzer) => {
+    if (analyzer.typescript.isCallExpression(expression) &&
+        analyzer.typescript.isIdentifier(expression.expression)) {
+        const mixinRef = getReferenceForIdentifier(expression.expression, analyzer);
+        try {
+            mixinRef?.dereference(MixinDeclaration);
+        }
+        catch (_err) {
+            return undefined;
+        }
+        const heritage = getHeritageFromExpression(expression, analyzer);
+        if (heritage.superClass) {
+            return new ClassDeclaration({
+                name: identifier.text,
+                node: expression,
+                getHeritage: () => heritage,
+            });
+        }
+    }
+    return undefined;
+};
+//# sourceMappingURL=classes.js.map

package/lib/javascript/classes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classes.js","sourceRoot":"","sources":["../../src/lib/javascript/classes.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 class declarations\n */\n\nimport type ts from 'typescript';\nimport {DiagnosticCode} from '../diagnostic-code.js';\nimport {createDiagnostic} from '../errors.js';\nimport {\n  ClassDeclaration,\n  AnalyzerInterface,\n  DeclarationInfo,\n  ClassHeritage,\n  Reference,\n  ClassField,\n  ClassMethod,\n  MixinDeclaration,\n} from '../model.js';\nimport {\n  isLitElementSubclass,\n  getLitElementDeclaration,\n} from '../lit-element/lit-element.js';\nimport {getReferenceForIdentifier} from '../references.js';\nimport {parseNodeJSDocInfo} from './jsdoc.js';\nimport {\n  hasDefaultModifier,\n  hasStaticModifier,\n  hasExportModifier,\n  getPrivacy,\n} from '../utils.js';\nimport {getFunctionLikeInfo} from './functions.js';\nimport {getTypeForNode} from '../types.js';\nimport {\n  isCustomElementSubclass,\n  getCustomElementDeclaration,\n} from '../custom-elements/custom-elements.js';\n\nexport type TypeScript = typeof ts;\n\n/**\n * Returns an analyzer `ClassDeclaration` model for the given\n * ts.ClassLikeDeclaration.\n *\n * Note, the `docNode` may differ from the `declaration` in the case of a const\n * assignment to a class expression, as the JSDoc will be attached to the\n * VariableStatement rather than the class-like expression.\n */\nexport const getClassDeclaration = (\n  declaration: ts.ClassLikeDeclaration,\n  name: string,\n  analyzer: AnalyzerInterface,\n  docNode?: ts.Node,\n  isMixinClass?: boolean\n) => {\n  if (isLitElementSubclass(declaration, analyzer)) {\n    return getLitElementDeclaration(declaration, analyzer, isMixinClass);\n  }\n  if (isCustomElementSubclass(declaration, analyzer)) {\n    return getCustomElementDeclaration(declaration, analyzer, isMixinClass);\n  }\n  return new ClassDeclaration({\n    name,\n    node: declaration,\n    getHeritage: () => getHeritage(declaration, analyzer, isMixinClass),\n    ...parseNodeJSDocInfo(docNode ?? declaration, analyzer),\n    ...getClassMembers(declaration, analyzer),\n  });\n};\n\nconst getIsReadonlyForNode = (\n  node: ts.Node,\n  analyzer: AnalyzerInterface\n): boolean => {\n  const {typescript} = analyzer;\n  if (typescript.isPropertyDeclaration(node)) {\n    return (\n      node.modifiers?.some((mod) =>\n        typescript.isReadonlyKeywordOrPlusOrMinusToken(mod)\n      ) ||\n      typescript\n        .getJSDocTags(node)\n        .some((tag) => tag.tagName.text === 'readonly')\n    );\n  } else if (typescript.isStatement(node)) {\n    return typescript\n      .getJSDocTags(node)\n      .some((tag) => tag.tagName.text === 'readonly');\n  }\n  return false;\n};\n\n/**\n * Returns the `fields` and `methods` of a class.\n */\nexport const getClassMembers = (\n  declaration: ts.ClassLikeDeclaration,\n  analyzer: AnalyzerInterface\n) => {\n  const {typescript} = analyzer;\n  const fieldMap = new Map<string, ClassField>();\n  const staticFieldMap = new Map<string, ClassField>();\n  const methodMap = new Map<string, ClassMethod>();\n  const staticMethodMap = new Map<string, ClassMethod>();\n  const accessors = new Map<\n    string,\n    {get?: ts.AccessorDeclaration; set?: ts.AccessorDeclaration}\n  >();\n  declaration.members.forEach((member) => {\n    // Ignore non-implementation signatures of overloaded methods by checking\n    // for `node.body`.\n    if (typescript.isConstructorDeclaration(member) && member.body) {\n      // TODO(bennypowers): We probably want to see if this matches what TypeScript considers a field initialization.\n      // Maybe instead of iterating through the constructor statements, we walk the body looking for any\n      // assignment expression so that we get ones inside of if statements, in parenthesized expressions, etc.\n      //\n      // Also, this doesn't cover destructuring assignment.\n      //\n      // This is ok for now because these are rare ways to \"declare\" a field,\n      // especially in web components where you shouldn't have constructor parameters.\n      member.body.statements.forEach((statement) => {\n        if (\n          typescript.isExpressionStatement(statement) &&\n          isConstructorFieldInitializer(statement.expression, typescript)\n        ) {\n          const name = statement.expression.left.name.getText();\n          fieldMap.set(\n            name,\n            new ClassField({\n              name,\n              type: getTypeForNode(statement.expression.right, analyzer),\n              privacy: getPrivacy(typescript, statement),\n              readonly: getIsReadonlyForNode(statement, analyzer),\n              node: statement.expression,\n            })\n          );\n        }\n      });\n    } else if (typescript.isMethodDeclaration(member) && member.body) {\n      const info = getMemberInfo(typescript, member);\n      const name = member.name.getText();\n      (info.static ? staticMethodMap : methodMap).set(\n        name,\n        new ClassMethod({\n          ...info,\n          ...getFunctionLikeInfo(member, name, analyzer),\n          ...parseNodeJSDocInfo(member, analyzer),\n          node: member,\n        })\n      );\n    } else if (typescript.isPropertyDeclaration(member)) {\n      if (\n        !typescript.isIdentifier(member.name) &&\n        !typescript.isPrivateIdentifier(member.name)\n      ) {\n        analyzer.addDiagnostic(\n          createDiagnostic({\n            typescript,\n            node: member,\n            message:\n              '@lit-labs/analyzer only supports analyzing class properties ' +\n              'named with plain identifiers, or private class fields. This ' +\n              'property was ignored: ' +\n              member.name.getText(),\n            category: typescript.DiagnosticCategory.Warning,\n            code: DiagnosticCode.UNSUPPORTED,\n          })\n        );\n        return;\n      }\n\n      const info = getMemberInfo(typescript, member);\n\n      (info.static ? staticFieldMap : fieldMap).set(\n        member.name.getText(),\n        new ClassField({\n          ...info,\n          default: member.initializer?.getText(),\n          type: getTypeForNode(member, analyzer),\n          ...parseNodeJSDocInfo(member, analyzer),\n          readonly: getIsReadonlyForNode(member, analyzer),\n          node: member,\n        })\n      );\n    } else if (typescript.isAccessor(member)) {\n      const name = member.name.getText();\n      const _accessors = accessors.get(name) ?? {};\n      if (typescript.isGetAccessor(member)) _accessors.get = member;\n      else if (typescript.isSetAccessor(member)) _accessors.set = member;\n      accessors.set(name, _accessors);\n    }\n  });\n  for (const [name, {get, set}] of accessors) {\n    if (get ?? set) {\n      fieldMap.set(\n        name,\n        new ClassField({\n          name,\n          type: getTypeForNode((get ?? set)!, analyzer),\n          privacy: getPrivacy(typescript, (get ?? set)!),\n          readonly: !!get && !set,\n          // TODO(bennypowers): derive from getter?\n          // default: ???\n          // TODO(bennypowers): reflect, etc?\n          node: (set ?? get)!,\n        })\n      );\n    }\n  }\n  return {\n    fieldMap,\n    staticFieldMap,\n    methodMap,\n    staticMethodMap,\n  };\n};\n\nconst getMemberInfo = (\n  typescript: TypeScript,\n  node: ts.MethodDeclaration | ts.PropertyDeclaration\n) => {\n  return {\n    name: node.name.getText(),\n    static: hasStaticModifier(typescript, node),\n    privacy: getPrivacy(typescript, node),\n  };\n};\n\n/**\n * Returns the name of a class declaration.\n */\nconst getClassDeclarationName = (\n  declaration: ts.ClassDeclaration,\n  analyzer: AnalyzerInterface\n) => {\n  const name =\n    declaration.name?.text ??\n    // The only time a class declaration will not have a name is when it is\n    // a default export, aka `export default class { }`\n    (hasDefaultModifier(analyzer.typescript, declaration)\n      ? 'default'\n      : undefined);\n  if (name === undefined) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: declaration,\n        message: `Illegal syntax: a class declaration must either have a name or be a default export`,\n      })\n    );\n  }\n  return name;\n};\n\n/**\n * Returns name and model factory for a class declaration.\n */\nexport const getClassDeclarationInfo = (\n  declaration: ts.ClassDeclaration,\n  analyzer: AnalyzerInterface\n): DeclarationInfo | undefined => {\n  const name = getClassDeclarationName(declaration, analyzer);\n  if (name === undefined) {\n    return undefined;\n  }\n  return {\n    name,\n    node: declaration,\n    factory: () => getClassDeclaration(declaration, name, analyzer),\n    isExport: hasExportModifier(analyzer.typescript, declaration),\n  };\n};\n\n/**\n * Returns the superClass and any applied mixins for a given class declaration.\n */\nexport const getHeritage = (\n  declaration: ts.ClassLikeDeclarationBase,\n  analyzer: AnalyzerInterface,\n  isMixinClass?: boolean\n): ClassHeritage => {\n  const extendsClause = declaration.heritageClauses?.find(\n    (c) => c.token === analyzer.typescript.SyntaxKind.ExtendsKeyword\n  );\n  if (extendsClause !== undefined) {\n    if (extendsClause.types.length === 1) {\n      return getHeritageFromExpression(\n        extendsClause.types[0].expression,\n        analyzer,\n        isMixinClass\n      );\n    }\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: extendsClause,\n        message:\n          'Illegal syntax: did not expect extends clause to have multiple types',\n      })\n    );\n  }\n  // No extends clause; return empty heritage\n  return {\n    mixins: [],\n    superClass: undefined,\n  };\n};\n\nexport const getHeritageFromExpression = (\n  expression: ts.Expression,\n  analyzer: AnalyzerInterface,\n  isMixinClass?: boolean\n): ClassHeritage => {\n  const mixins: Reference[] = [];\n  const superClass = getSuperClassAndMixins(expression, mixins, analyzer);\n  return {\n    superClass: isMixinClass ? undefined : superClass,\n    mixins,\n  };\n};\n\nexport const getSuperClassAndMixins = (\n  expression: ts.Expression,\n  foundMixins: Reference[],\n  analyzer: AnalyzerInterface\n): Reference | undefined => {\n  // TODO(kschaaf) Could add support for inline class expressions here as well\n  if (analyzer.typescript.isIdentifier(expression)) {\n    return getReferenceForIdentifier(expression, analyzer);\n  } else if (\n    analyzer.typescript.isCallExpression(expression) &&\n    analyzer.typescript.isIdentifier(expression.expression)\n  ) {\n    // FYI we purposely restrict to identifiers since we represent mixins\n    // as references. If we want to support complex expressions in future,\n    // we will need to rework that in the model.\n    const mixinRef = getReferenceForIdentifier(expression.expression, analyzer);\n    // We need to eagerly dereference a mixin ref to know what argument the\n    // super class is passed into\n    let mixin;\n\n    try {\n      mixin = mixinRef?.dereference(MixinDeclaration);\n    } catch (_err) {\n      // It wasn't a MixinDeclaration for whatever reason\n      mixin = undefined;\n    }\n\n    // TODO (43081j): consider supporting external mixins properly at some point\n    // An external mixin is one which we discovered via analysis (e.g. CEM)\n    // but don't have a reference to in sources. In future, we should support\n    // those as it is likely we will pull most dependencies from manifest\n    // analysis rather than source.\n    // See issue #4492\n    if (mixinRef === undefined || mixin === undefined) {\n      analyzer.addDiagnostic(\n        createDiagnostic({\n          typescript: analyzer.typescript,\n          node: expression,\n          message:\n            `This is presumed to be a mixin but it could not be found ` +\n            `in the current project. Mixins imported from outside the ` +\n            `project are not yet supported ` +\n            `(see https://github.com/lit/lit/issues/4492).`,\n          code: DiagnosticCode.UNSUPPORTED,\n          category: analyzer.typescript.DiagnosticCategory.Warning,\n        })\n      );\n      return undefined;\n    }\n    foundMixins.push(mixinRef);\n    const superArg = expression.arguments[mixin.superClassArgIndex];\n    const superClass = getSuperClassAndMixins(superArg, foundMixins, analyzer);\n    return superClass;\n  }\n  analyzer.addDiagnostic(\n    createDiagnostic({\n      typescript: analyzer.typescript,\n      node: expression,\n      message: `Expected expression to be a concrete superclass or mixin.`,\n      code: DiagnosticCode.UNSUPPORTED,\n      category: analyzer.typescript.DiagnosticCategory.Warning,\n    })\n  );\n  return undefined;\n};\n\nexport const isConstructorFieldInitializer = (\n  expression: ts.Expression,\n  typescript: typeof ts\n): expression is ConstructorFieldInitializer => {\n  return (\n    typescript.isBinaryExpression(expression) &&\n    expression.operatorToken.kind === typescript.SyntaxKind.EqualsToken &&\n    typescript.isPropertyAccessExpression(expression.left) &&\n    expression.left.expression.kind === typescript.SyntaxKind.ThisKeyword\n  );\n};\n\ntype ConstructorFieldInitializer = ts.AssignmentExpression<ts.EqualsToken> & {\n  left: ts.PropertyAccessExpression & {expression: ts.ThisExpression};\n};\n\nexport const maybeGetAppliedMixin = (\n  expression: ts.Expression,\n  identifier: ts.Identifier,\n  analyzer: AnalyzerInterface\n): ClassDeclaration | undefined => {\n  if (\n    analyzer.typescript.isCallExpression(expression) &&\n    analyzer.typescript.isIdentifier(expression.expression)\n  ) {\n    const mixinRef = getReferenceForIdentifier(expression.expression, analyzer);\n\n    try {\n      mixinRef?.dereference(MixinDeclaration);\n    } catch (_err) {\n      return undefined;\n    }\n\n    const heritage = getHeritageFromExpression(expression, analyzer);\n\n    if (heritage.superClass) {\n      return new ClassDeclaration({\n        name: identifier.text,\n        node: expression,\n        getHeritage: () => heritage,\n      });\n    }\n  }\n  return undefined;\n};\n"]}

package/lib/javascript/functions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * @fileoverview
+ *
+ * Utilities for analyzing function declarations
+ */
+import type ts from 'typescript';
+import { AnalyzerInterface, DeclarationInfo, FunctionDeclaration, FunctionLikeInit } from '../model.js';
+export type TypeScript = typeof ts;
+export declare const getFunctionDeclarationInfo: (declaration: ts.FunctionDeclaration, analyzer: AnalyzerInterface) => DeclarationInfo | undefined;
+/**
+ * Returns an analyzer `FunctionDeclaration` model for the given
+ * ts.FunctionLikeDeclaration.
+ *
+ * If this is a mixin function, the return value will be a `MixinDeclaration`
+ * model instead.
+ *
+ * Note, the `docNode` may differ from the `declaration` in the case of a const
+ * assignment to a class expression, as the JSDoc will be attached to the
+ * VariableStatement rather than the class-like expression.
+ */
+export declare const getFunctionDeclaration: (declaration: ts.FunctionLikeDeclaration, name: string, analyzer: AnalyzerInterface, docNode?: ts.Node) => FunctionDeclaration;
+/**
+ * Returns information on FunctionLike nodes
+ */
+export declare const getFunctionLikeInfo: (node: ts.FunctionLikeDeclaration, name: string, analyzer: AnalyzerInterface) => FunctionLikeInit;
+//# sourceMappingURL=functions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../src/lib/javascript/functions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAKjB,MAAM,aAAa,CAAC;AAMrB,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAC;AA6BnC,eAAO,MAAM,0BAA0B,GACrC,aAAa,EAAE,CAAC,mBAAmB,EACnC,UAAU,iBAAiB,KAC1B,eAAe,GAAG,SAWpB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GACjC,aAAa,EAAE,CAAC,uBAAuB,EACvC,MAAM,MAAM,EACZ,UAAU,iBAAiB,EAC3B,UAAU,EAAE,CAAC,IAAI,KAChB,mBAmBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,EAAE,CAAC,uBAAuB,EAChC,MAAM,MAAM,EACZ,UAAU,iBAAiB,KAC1B,gBAkCF,CAAC"}

package/lib/javascript/functions.js

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { createDiagnostic } from '../errors.js';
+import { FunctionDeclaration, FunctionOverloadDeclaration, MixinDeclaration, } from '../model.js';
+import { getTypeForNode, getTypeForType } from '../types.js';
+import { maybeGetMixinFromFunctionLike } from './mixins.js';
+import { parseJSDocDescription, parseNodeJSDocInfo } from './jsdoc.js';
+import { hasDefaultModifier, hasExportModifier } from '../utils.js';
+/**
+ * Returns the name of a function declaration.
+ */
+const getFunctionDeclarationName = (declaration, analyzer) => {
+    const name = declaration.name?.text ??
+        // The only time a function declaration will not have a name is when it is
+        // a default export, aka `export default function() {...}`
+        (hasDefaultModifier(analyzer.typescript, declaration)
+            ? 'default'
+            : undefined);
+    if (name === undefined) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: declaration,
+            message: 'Illegal syntax: expected every function declaration to either have a name or be a default export',
+        }));
+    }
+    return name;
+};
+export const getFunctionDeclarationInfo = (declaration, analyzer) => {
+    const name = getFunctionDeclarationName(declaration, analyzer);
+    if (name === undefined) {
+        return undefined;
+    }
+    return {
+        name,
+        node: declaration,
+        factory: () => getFunctionDeclaration(declaration, name, analyzer),
+        isExport: hasExportModifier(analyzer.typescript, declaration),
+    };
+};
+/**
+ * Returns an analyzer `FunctionDeclaration` model for the given
+ * ts.FunctionLikeDeclaration.
+ *
+ * If this is a mixin function, the return value will be a `MixinDeclaration`
+ * model instead.
+ *
+ * Note, the `docNode` may differ from the `declaration` in the case of a const
+ * assignment to a class expression, as the JSDoc will be attached to the
+ * VariableStatement rather than the class-like expression.
+ */
+export const getFunctionDeclaration = (declaration, name, analyzer, docNode) => {
+    const mixinDeclarationInfo = maybeGetMixinFromFunctionLike(declaration, name, analyzer);
+    if (mixinDeclarationInfo !== undefined) {
+        return new MixinDeclaration({
+            ...mixinDeclarationInfo,
+            ...parseNodeJSDocInfo(docNode ?? declaration, analyzer),
+            ...getFunctionLikeInfo(declaration, name, analyzer),
+        });
+    }
+    return new FunctionDeclaration({
+        ...parseNodeJSDocInfo(docNode ?? declaration, analyzer),
+        ...getFunctionLikeInfo(declaration, name, analyzer),
+    });
+};
+/**
+ * Returns information on FunctionLike nodes
+ */
+export const getFunctionLikeInfo = (node, name, analyzer) => {
+    let overloads = undefined;
+    if (node.body) {
+        // Overloaded functions have multiple declaration nodes.
+        const type = analyzer.program.getTypeChecker().getTypeAtLocation(node);
+        const overloadDeclarations = type
+            .getSymbol()
+            ?.getDeclarations()
+            ?.filter((x) => x !== node);
+        overloads = overloadDeclarations?.map((overload) => {
+            const info = getFunctionLikeInfo(overload, name, analyzer);
+            return new FunctionOverloadDeclaration({
+                // `docNode ?? overload` isn't needed here because TS doesn't allow
+                // const function assignments to be overloaded as of now.
+                ...parseNodeJSDocInfo(overload, analyzer),
+                // `info` can't be spread because `FunctionLikeInit` has an `overloads`
+                // property, even though it's always `undefined` in this case.
+                name: info.name,
+                parameters: info.parameters,
+                return: info.return,
+                node: overload,
+            });
+        });
+    }
+    return {
+        name,
+        parameters: node.parameters.map((p) => getParameter(p, analyzer)),
+        return: getReturn(node, analyzer),
+        overloads,
+        node,
+    };
+};
+const getParameter = (param, analyzer) => {
+    const paramTag = analyzer.typescript.getAllJSDocTagsOfKind(param, analyzer.typescript.SyntaxKind.JSDocParameterTag)[0];
+    const p = {
+        name: param.name.getText(),
+        node: param,
+        type: getTypeForNode(param, analyzer),
+        ...(paramTag ? parseJSDocDescription(paramTag, analyzer) : {}),
+        optional: false,
+        rest: false,
+    };
+    if (param.initializer !== undefined) {
+        p.optional = true;
+        p.default = param.initializer.getText();
+    }
+    if (param.questionToken !== undefined) {
+        p.optional = true;
+    }
+    if (param.dotDotDotToken !== undefined) {
+        p.rest = true;
+    }
+    return p;
+};
+const getReturn = (node, analyzer) => {
+    const returnTag = analyzer.typescript.getAllJSDocTagsOfKind(node, analyzer.typescript.SyntaxKind.JSDocReturnTag)[0];
+    const signature = analyzer.program
+        .getTypeChecker()
+        .getSignatureFromDeclaration(node);
+    if (signature === undefined) {
+        // TODO: when does this happen? is it actionable for the user? if so, how?
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node,
+            message: `Could not get signature to determine return type`,
+        }));
+        return undefined;
+    }
+    return {
+        type: getTypeForType(signature.getReturnType(), node, analyzer),
+        ...(returnTag ? parseJSDocDescription(returnTag, analyzer) : {}),
+    };
+};
+//# sourceMappingURL=functions.js.map

package/lib/javascript/functions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.js","sourceRoot":"","sources":["../../src/lib/javascript/functions.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 function declarations\n */\n\nimport type ts from 'typescript';\nimport {createDiagnostic} from '../errors.js';\nimport {\n  AnalyzerInterface,\n  DeclarationInfo,\n  FunctionDeclaration,\n  FunctionLikeInit,\n  FunctionOverloadDeclaration,\n  Parameter,\n  Return,\n  MixinDeclaration,\n} from '../model.js';\nimport {getTypeForNode, getTypeForType} from '../types.js';\nimport {maybeGetMixinFromFunctionLike} from './mixins.js';\nimport {parseJSDocDescription, parseNodeJSDocInfo} from './jsdoc.js';\nimport {hasDefaultModifier, hasExportModifier} from '../utils.js';\n\nexport type TypeScript = typeof ts;\n\n/**\n * Returns the name of a function declaration.\n */\nconst getFunctionDeclarationName = (\n  declaration: ts.FunctionDeclaration,\n  analyzer: AnalyzerInterface\n) => {\n  const name =\n    declaration.name?.text ??\n    // The only time a function declaration will not have a name is when it is\n    // a default export, aka `export default function() {...}`\n    (hasDefaultModifier(analyzer.typescript, declaration)\n      ? 'default'\n      : undefined);\n  if (name === undefined) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: declaration,\n        message:\n          'Illegal syntax: expected every function declaration to either have a name or be a default export',\n      })\n    );\n  }\n  return name;\n};\n\nexport const getFunctionDeclarationInfo = (\n  declaration: ts.FunctionDeclaration,\n  analyzer: AnalyzerInterface\n): DeclarationInfo | undefined => {\n  const name = getFunctionDeclarationName(declaration, analyzer);\n  if (name === undefined) {\n    return undefined;\n  }\n  return {\n    name,\n    node: declaration,\n    factory: () => getFunctionDeclaration(declaration, name, analyzer),\n    isExport: hasExportModifier(analyzer.typescript, declaration),\n  };\n};\n\n/**\n * Returns an analyzer `FunctionDeclaration` model for the given\n * ts.FunctionLikeDeclaration.\n *\n * If this is a mixin function, the return value will be a `MixinDeclaration`\n * model instead.\n *\n * Note, the `docNode` may differ from the `declaration` in the case of a const\n * assignment to a class expression, as the JSDoc will be attached to the\n * VariableStatement rather than the class-like expression.\n */\nexport const getFunctionDeclaration = (\n  declaration: ts.FunctionLikeDeclaration,\n  name: string,\n  analyzer: AnalyzerInterface,\n  docNode?: ts.Node\n): FunctionDeclaration => {\n  const mixinDeclarationInfo = maybeGetMixinFromFunctionLike(\n    declaration,\n    name,\n    analyzer\n  );\n\n  if (mixinDeclarationInfo !== undefined) {\n    return new MixinDeclaration({\n      ...mixinDeclarationInfo,\n      ...parseNodeJSDocInfo(docNode ?? declaration, analyzer),\n      ...getFunctionLikeInfo(declaration, name, analyzer),\n    });\n  }\n\n  return new FunctionDeclaration({\n    ...parseNodeJSDocInfo(docNode ?? declaration, analyzer),\n    ...getFunctionLikeInfo(declaration, name, analyzer),\n  });\n};\n\n/**\n * Returns information on FunctionLike nodes\n */\nexport const getFunctionLikeInfo = (\n  node: ts.FunctionLikeDeclaration,\n  name: string,\n  analyzer: AnalyzerInterface\n): FunctionLikeInit => {\n  let overloads = undefined;\n  if (node.body) {\n    // Overloaded functions have multiple declaration nodes.\n    const type = analyzer.program.getTypeChecker().getTypeAtLocation(node);\n    const overloadDeclarations = type\n      .getSymbol()\n      ?.getDeclarations()\n      ?.filter((x) => x !== node) as Array<ts.FunctionLikeDeclaration>;\n\n    overloads = overloadDeclarations?.map((overload) => {\n      const info = getFunctionLikeInfo(overload, name, analyzer);\n      return new FunctionOverloadDeclaration({\n        // `docNode ?? overload` isn't needed here because TS doesn't allow\n        // const function assignments to be overloaded as of now.\n        ...parseNodeJSDocInfo(overload, analyzer),\n\n        // `info` can't be spread because `FunctionLikeInit` has an `overloads`\n        // property, even though it's always `undefined` in this case.\n        name: info.name,\n        parameters: info.parameters,\n        return: info.return,\n        node: overload,\n      });\n    });\n  }\n\n  return {\n    name,\n    parameters: node.parameters.map((p) => getParameter(p, analyzer)),\n    return: getReturn(node, analyzer),\n    overloads,\n    node,\n  };\n};\n\nconst getParameter = (\n  param: ts.ParameterDeclaration,\n  analyzer: AnalyzerInterface\n): Parameter => {\n  const paramTag = analyzer.typescript.getAllJSDocTagsOfKind(\n    param,\n    analyzer.typescript.SyntaxKind.JSDocParameterTag\n  )[0];\n  const p: Parameter = {\n    name: param.name.getText(),\n    node: param,\n    type: getTypeForNode(param, analyzer),\n    ...(paramTag ? parseJSDocDescription(paramTag, analyzer) : {}),\n    optional: false,\n    rest: false,\n  };\n  if (param.initializer !== undefined) {\n    p.optional = true;\n    p.default = param.initializer.getText();\n  }\n  if (param.questionToken !== undefined) {\n    p.optional = true;\n  }\n  if (param.dotDotDotToken !== undefined) {\n    p.rest = true;\n  }\n  return p;\n};\n\nconst getReturn = (\n  node: ts.FunctionLikeDeclaration,\n  analyzer: AnalyzerInterface\n): Return | undefined => {\n  const returnTag = analyzer.typescript.getAllJSDocTagsOfKind(\n    node,\n    analyzer.typescript.SyntaxKind.JSDocReturnTag\n  )[0];\n  const signature = analyzer.program\n    .getTypeChecker()\n    .getSignatureFromDeclaration(node);\n  if (signature === undefined) {\n    // TODO: when does this happen? is it actionable for the user? if so, how?\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node,\n        message: `Could not get signature to determine return type`,\n      })\n    );\n    return undefined;\n  }\n  return {\n    type: getTypeForType(signature.getReturnType(), node, analyzer),\n    ...(returnTag ? parseJSDocDescription(returnTag, analyzer) : {}),\n  };\n};\n"]}