@oicl-lit/analyzer 0.14.1

package/lib/javascript/jsdoc.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * @fileoverview
+ *
+ * Utilities for analyzing JSDoc comments
+ */
+import type ts from 'typescript';
+import { Described, TypedNamedDescribed, DeprecatableDescribed, AnalyzerInterface } from '../model.js';
+export type TypeScript = typeof ts;
+/**
+ * @fileoverview
+ *
+ * Utilities for parsing JSDoc comments.
+ */
+/**
+ * Returns true if given node has a JSDoc tag
+ */
+export declare const hasJSDocTag: (ts: TypeScript, node: ts.Node, tag: string) => boolean;
+/**
+ * Parses name, type, and description from JSDoc tag for things like `@fires`.
+ *
+ * Supports the following patterns following the tag (TS parses the tag for us):
+ * * @fires event-name
+ * * @fires event-name description
+ * * @fires event-name - description
+ * * @fires event-name: description
+ * * @fires event-name {Type}
+ * * @fires event-name {Type} description
+ * * @fires event-name {Type} - description
+ * * @fires event-name {Type}: description
+ * * @fires {Type} event-name
+ * * @fires {Type} event-name description
+ * * @fires {Type} event-name - description
+ * * @fires {Type} event-name: description
+ * * @slot name
+ * * @slot name description
+ * * @slot name - description
+ * * @slot name: description
+ * * @cssProp [--name=default]
+ * * @cssProp [--name=default] description
+ * * @cssProp [--name=default] - description
+ * * @cssProp [--name=default]: description
+ * * @cssprop {<color>} [--name=default]
+ * * @cssprop {<color>} [--name=default] description
+ * * @cssprop {<color>} [--name=default] - description
+ * * @cssprop {<color>} [--name=default]: description
+ */
+export declare const parseNamedTypedJSDocInfo: (tag: ts.JSDocTag, analyzer: AnalyzerInterface) => TypedNamedDescribed | undefined;
+/**
+ * Parses the description from JSDoc tag for things like `@return`.
+ */
+export declare const parseJSDocDescription: (tag: ts.JSDocTag, analyzer: AnalyzerInterface) => Described | undefined;
+/**
+ * Parse summary, description, and deprecated information from JSDoc comments on
+ * a given node.
+ */
+export declare const parseNodeJSDocInfo: (node: ts.Node, analyzer: AnalyzerInterface) => DeprecatableDescribed;
+/**
+ * Parse summary, description, and deprecated information from JSDoc comments on
+ * a given source file.
+ */
+export declare const parseModuleJSDocInfo: (sourceFile: ts.SourceFile, analyzer: AnalyzerInterface) => DeprecatableDescribed;
+//# sourceMappingURL=jsdoc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsdoc.d.ts","sourceRoot":"","sources":["../../src/lib/javascript/jsdoc.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAC;AAEnC;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,UAAU,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,MAAM,YAErE,CAAC;AA0CF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,wBAAwB,GACnC,KAAK,EAAE,CAAC,QAAQ,EAChB,UAAU,iBAAiB,oCAiC5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAChC,KAAK,EAAE,CAAC,QAAQ,EAChB,UAAU,iBAAiB,KAC1B,SAAS,GAAG,SAMd,CAAC;AAoFF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,EAAE,CAAC,IAAI,EACb,UAAU,iBAAiB,KAC1B,qBA+BF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,EAAE,CAAC,UAAU,EACzB,UAAU,iBAAiB,0BAmB5B,CAAC"}

package/lib/javascript/jsdoc.js

@@ -0,0 +1,244 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { createDiagnostic } from '../errors.js';
+/**
+ * @fileoverview
+ *
+ * Utilities for parsing JSDoc comments.
+ */
+/**
+ * Returns true if given node has a JSDoc tag
+ */
+export const hasJSDocTag = (ts, node, tag) => {
+    return ts.getJSDocTags(node).some((t) => t.tagName.text === tag);
+};
+/**
+ * Remove line feeds from JSDoc comments, so they are normalized to
+ * unix `\n` line endings.
+ */
+const normalizeLineEndings = (s) => s.replace(/\r/g, '').trim();
+// Regex for parsing name, type, and description from JSDoc comments
+const parseNameTypeDescRE = /^\[?(?<name>[^{}[\]\s=]+)(?:=(?<defaultValue>[^\]]+))?\]?(?:\s+{(?<type>.*)})?(?:\s+-\s+)?(?<description>[\s\S]*)$/m;
+// Regex for parsing type, name, and description from JSDoc comments
+const parseTypeNameDescRE = /^\{(?<type>.+)\}\s+\[?(?<name>[^{}[\]\s=]+)(?:=(?<defaultValue>[^\]]+))?\]?(?:\s+-\s+)?(?<description>[\s\S]*)$/m;
+const getJSDocTagComment = (tag, analyzer) => {
+    let { comment } = tag;
+    if (comment === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(comment)) {
+        comment = comment.map((c) => c.text).join('');
+    }
+    if (typeof comment !== 'string') {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: tag,
+            message: `JSDoc error: unsupported node type`,
+        }));
+        return undefined;
+    }
+    return normalizeLineEndings(comment).trim();
+};
+const isModuleJSDocTag = (tag) => tag.tagName.text === 'module' ||
+    tag.tagName.text === 'fileoverview' ||
+    tag.tagName.text === 'packageDocumentation';
+/**
+ * Parses name, type, and description from JSDoc tag for things like `@fires`.
+ *
+ * Supports the following patterns following the tag (TS parses the tag for us):
+ * * @fires event-name
+ * * @fires event-name description
+ * * @fires event-name - description
+ * * @fires event-name: description
+ * * @fires event-name {Type}
+ * * @fires event-name {Type} description
+ * * @fires event-name {Type} - description
+ * * @fires event-name {Type}: description
+ * * @fires {Type} event-name
+ * * @fires {Type} event-name description
+ * * @fires {Type} event-name - description
+ * * @fires {Type} event-name: description
+ * * @slot name
+ * * @slot name description
+ * * @slot name - description
+ * * @slot name: description
+ * * @cssProp [--name=default]
+ * * @cssProp [--name=default] description
+ * * @cssProp [--name=default] - description
+ * * @cssProp [--name=default]: description
+ * * @cssprop {<color>} [--name=default]
+ * * @cssprop {<color>} [--name=default] description
+ * * @cssprop {<color>} [--name=default] - description
+ * * @cssprop {<color>} [--name=default]: description
+ */
+export const parseNamedTypedJSDocInfo = (tag, analyzer) => {
+    const comment = getJSDocTagComment(tag, analyzer);
+    if (comment == undefined) {
+        return undefined;
+    }
+    const regex = comment.charAt(0) === '{' ? parseTypeNameDescRE : parseNameTypeDescRE;
+    const nameTypeDesc = comment.match(regex);
+    if (nameTypeDesc === null) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: tag,
+            message: `JSDoc error: unexpected JSDoc format`,
+        }));
+        return undefined;
+    }
+    const { name, type, defaultValue, description } = nameTypeDesc.groups;
+    const info = { name };
+    if (description.length > 0) {
+        info.description = normalizeLineEndings(description);
+    }
+    if (defaultValue?.length > 0) {
+        info.default = defaultValue;
+    }
+    if (tag.tagName.text.toLowerCase().startsWith('cssprop')) {
+        info.syntax = type;
+    }
+    else {
+        info.type = type;
+    }
+    return info;
+};
+/**
+ * Parses the description from JSDoc tag for things like `@return`.
+ */
+export const parseJSDocDescription = (tag, analyzer) => {
+    const description = getJSDocTagComment(tag, analyzer);
+    if (description == undefined || description.length === 0) {
+        return {};
+    }
+    return { description };
+};
+/**
+ * Add `@description`, `@summary`, and `@deprecated` JSDoc tag info to the
+ * given info object.
+ */
+const addJSDocTagInfo = (info, jsDocTags, analyzer) => {
+    for (const tag of jsDocTags) {
+        const comment = getJSDocTagComment(tag, analyzer);
+        switch (tag.tagName.text.toLowerCase()) {
+            case 'description':
+            case 'fileoverview':
+            case 'packagedocumentation':
+                if (comment !== undefined) {
+                    info.description = comment;
+                }
+                break;
+            case 'summary':
+                if (comment !== undefined) {
+                    info.summary = comment;
+                }
+                break;
+            case 'deprecated':
+                info.deprecated = comment !== undefined ? comment : true;
+                break;
+        }
+    }
+};
+const moduleJSDocsMap = new WeakMap();
+/**
+ * Returns the module-level JSDoc comment blocks for a given source file.
+ *
+ * Note that TS does not have a concept of module-level JSDoc; if it
+ * exists, it will always be attached to the first statement in the module.
+ *
+ * Thus, we parse module-level documentation using the following heuristic:
+ * - If the first statement only has one JSDoc block, it is only treated as
+ *   module documentation if it contains a `@module`, `@fileoverview`, or
+ *   `@packageDocumentation` tag. This is required to disambiguate a module
+ *   description (with an undocumented first statement) from documentation
+ *   for the first statement.
+ * - If the first statement has more than one JSDoc block, we collect all
+ *   but the last and use those, regardless of whether they contain one
+ *   of the above module-designating tags (the last one is assumed to belong
+ *   to the first statement).
+ *
+ * This function caches its result against the given sourceFile, since it is
+ * needed both to find the module comment and to filter out module comments
+ * node comments.
+ */
+const getModuleJSDocs = (typescript, sourceFile) => {
+    let moduleJSDocs = moduleJSDocsMap.get(sourceFile);
+    if (moduleJSDocs !== undefined) {
+        return moduleJSDocs;
+    }
+    // Get the first child in the sourceFile; note that returning the first child
+    // from `ts.forEachChild` is more robust than `sourceFile.getChildAt(0)`,
+    // since `forEachChild` flattens embedded arrays that the child APIs would
+    // otherwise return.
+    const firstChild = typescript.forEachChild(sourceFile, (n) => n);
+    if (firstChild === undefined) {
+        moduleJSDocs = [];
+    }
+    else {
+        // Get the JSDoc blocks attached to the first child (they oddly show up
+        // in the node's children)
+        const jsDocs = firstChild.getChildren().filter(typescript.isJSDoc);
+        // If there is more than one leading JSDoc block, grab all but the last,
+        // otherwise grab the one (see heuristic above)
+        moduleJSDocs = jsDocs.slice(0, jsDocs.length > 1 ? -1 : 1);
+        // If there is only one leading JSDoc block, it must have a module tag
+        if (jsDocs.length === 1 && !jsDocs[0].tags?.some(isModuleJSDocTag)) {
+            moduleJSDocs = [];
+        }
+    }
+    moduleJSDocsMap.set(sourceFile, moduleJSDocs);
+    return moduleJSDocs;
+};
+/**
+ * Parse summary, description, and deprecated information from JSDoc comments on
+ * a given node.
+ */
+export const parseNodeJSDocInfo = (node, analyzer) => {
+    const info = {};
+    const moduleJSDocs = getModuleJSDocs(analyzer.typescript, node.getSourceFile());
+    // Module-level docs (that are explicitly tagged as such) may be
+    // attached to the first declaration if the declaration is undocumented,
+    // so we filter those out since they shouldn't apply to a
+    // declaration node
+    const jsDocTags = analyzer.typescript
+        .getJSDocTags(node)
+        .filter(({ parent }) => !moduleJSDocs.includes(parent));
+    if (jsDocTags !== undefined) {
+        addJSDocTagInfo(info, jsDocTags, analyzer);
+    }
+    if (info.description === undefined) {
+        const comment = normalizeLineEndings(node
+            .getChildren()
+            .filter(analyzer.typescript.isJSDoc)
+            .filter((c) => !moduleJSDocs.includes(c))
+            .map((n) => n.comment)
+            .filter((c) => c !== undefined)
+            .join('\n'));
+        if (comment.length > 0) {
+            info.description = comment;
+        }
+    }
+    return info;
+};
+/**
+ * Parse summary, description, and deprecated information from JSDoc comments on
+ * a given source file.
+ */
+export const parseModuleJSDocInfo = (sourceFile, analyzer) => {
+    const moduleJSDocs = getModuleJSDocs(analyzer.typescript, sourceFile);
+    const info = {};
+    addJSDocTagInfo(info, moduleJSDocs.flatMap((m) => m.tags ?? []), analyzer);
+    if (info.description === undefined) {
+        const comment = moduleJSDocs
+            .map((d) => d.comment)
+            .filter((c) => c !== undefined)
+            .join('\n');
+        if (comment.length > 0) {
+            info.description = comment;
+        }
+    }
+    return info;
+};
+//# sourceMappingURL=jsdoc.js.map

package/lib/javascript/jsdoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsdoc.js","sourceRoot":"","sources":["../../src/lib/javascript/jsdoc.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 JSDoc comments\n */\n\nimport type ts from 'typescript';\nimport {createDiagnostic} from '../errors.js';\nimport {\n  Described,\n  TypedNamedDescribed,\n  DeprecatableDescribed,\n  AnalyzerInterface,\n  CSSPropertyInfo,\n} from '../model.js';\n\nexport type TypeScript = typeof ts;\n\n/**\n * @fileoverview\n *\n * Utilities for parsing JSDoc comments.\n */\n\n/**\n * Returns true if given node has a JSDoc tag\n */\nexport const hasJSDocTag = (ts: TypeScript, node: ts.Node, tag: string) => {\n  return ts.getJSDocTags(node).some((t) => t.tagName.text === tag);\n};\n\n/**\n * Remove line feeds from JSDoc comments, so they are normalized to\n * unix `\\n` line endings.\n */\nconst normalizeLineEndings = (s: string) => s.replace(/\\r/g, '').trim();\n\n// Regex for parsing name, type, and description from JSDoc comments\nconst parseNameTypeDescRE =\n  /^\\[?(?<name>[^{}[\\]\\s=]+)(?:=(?<defaultValue>[^\\]]+))?\\]?(?:\\s+{(?<type>.*)})?(?:\\s+-\\s+)?(?<description>[\\s\\S]*)$/m;\n\n// Regex for parsing type, name, and description from JSDoc comments\nconst parseTypeNameDescRE =\n  /^\\{(?<type>.+)\\}\\s+\\[?(?<name>[^{}[\\]\\s=]+)(?:=(?<defaultValue>[^\\]]+))?\\]?(?:\\s+-\\s+)?(?<description>[\\s\\S]*)$/m;\n\nconst getJSDocTagComment = (tag: ts.JSDocTag, analyzer: AnalyzerInterface) => {\n  let {comment} = tag;\n  if (comment === undefined) {\n    return undefined;\n  }\n  if (Array.isArray(comment)) {\n    comment = comment.map((c) => c.text).join('');\n  }\n  if (typeof comment !== 'string') {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: tag,\n        message: `JSDoc error: unsupported node type`,\n      })\n    );\n    return undefined;\n  }\n  return normalizeLineEndings(comment).trim();\n};\n\nconst isModuleJSDocTag = (tag: ts.JSDocTag) =>\n  tag.tagName.text === 'module' ||\n  tag.tagName.text === 'fileoverview' ||\n  tag.tagName.text === 'packageDocumentation';\n\n/**\n * Parses name, type, and description from JSDoc tag for things like `@fires`.\n *\n * Supports the following patterns following the tag (TS parses the tag for us):\n * * @fires event-name\n * * @fires event-name description\n * * @fires event-name - description\n * * @fires event-name: description\n * * @fires event-name {Type}\n * * @fires event-name {Type} description\n * * @fires event-name {Type} - description\n * * @fires event-name {Type}: description\n * * @fires {Type} event-name\n * * @fires {Type} event-name description\n * * @fires {Type} event-name - description\n * * @fires {Type} event-name: description\n * * @slot name\n * * @slot name description\n * * @slot name - description\n * * @slot name: description\n * * @cssProp [--name=default]\n * * @cssProp [--name=default] description\n * * @cssProp [--name=default] - description\n * * @cssProp [--name=default]: description\n * * @cssprop {<color>} [--name=default]\n * * @cssprop {<color>} [--name=default] description\n * * @cssprop {<color>} [--name=default] - description\n * * @cssprop {<color>} [--name=default]: description\n */\nexport const parseNamedTypedJSDocInfo = (\n  tag: ts.JSDocTag,\n  analyzer: AnalyzerInterface\n) => {\n  const comment = getJSDocTagComment(tag, analyzer);\n  if (comment == undefined) {\n    return undefined;\n  }\n  const regex =\n    comment.charAt(0) === '{' ? parseTypeNameDescRE : parseNameTypeDescRE;\n  const nameTypeDesc = comment.match(regex);\n  if (nameTypeDesc === null) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: tag,\n        message: `JSDoc error: unexpected JSDoc format`,\n      })\n    );\n    return undefined;\n  }\n  const {name, type, defaultValue, description} = nameTypeDesc.groups!;\n  const info: TypedNamedDescribed = {name};\n  if (description.length > 0) {\n    info.description = normalizeLineEndings(description);\n  }\n  if (defaultValue?.length > 0) {\n    info.default = defaultValue;\n  }\n  if (tag.tagName.text.toLowerCase().startsWith('cssprop')) {\n    (info as CSSPropertyInfo).syntax = type;\n  } else {\n    info.type = type;\n  }\n  return info;\n};\n\n/**\n * Parses the description from JSDoc tag for things like `@return`.\n */\nexport const parseJSDocDescription = (\n  tag: ts.JSDocTag,\n  analyzer: AnalyzerInterface\n): Described | undefined => {\n  const description = getJSDocTagComment(tag, analyzer);\n  if (description == undefined || description.length === 0) {\n    return {};\n  }\n  return {description};\n};\n\n/**\n * Add `@description`, `@summary`, and `@deprecated` JSDoc tag info to the\n * given info object.\n */\nconst addJSDocTagInfo = (\n  info: DeprecatableDescribed,\n  jsDocTags: readonly ts.JSDocTag[],\n  analyzer: AnalyzerInterface\n) => {\n  for (const tag of jsDocTags) {\n    const comment = getJSDocTagComment(tag, analyzer);\n    switch (tag.tagName.text.toLowerCase()) {\n      case 'description':\n      case 'fileoverview':\n      case 'packagedocumentation':\n        if (comment !== undefined) {\n          info.description = comment;\n        }\n        break;\n      case 'summary':\n        if (comment !== undefined) {\n          info.summary = comment;\n        }\n        break;\n      case 'deprecated':\n        info.deprecated = comment !== undefined ? comment : true;\n        break;\n    }\n  }\n};\n\nconst moduleJSDocsMap = new WeakMap<ts.SourceFile, ts.JSDoc[]>();\n\n/**\n * Returns the module-level JSDoc comment blocks for a given source file.\n *\n * Note that TS does not have a concept of module-level JSDoc; if it\n * exists, it will always be attached to the first statement in the module.\n *\n * Thus, we parse module-level documentation using the following heuristic:\n * - If the first statement only has one JSDoc block, it is only treated as\n *   module documentation if it contains a `@module`, `@fileoverview`, or\n *   `@packageDocumentation` tag. This is required to disambiguate a module\n *   description (with an undocumented first statement) from documentation\n *   for the first statement.\n * - If the first statement has more than one JSDoc block, we collect all\n *   but the last and use those, regardless of whether they contain one\n *   of the above module-designating tags (the last one is assumed to belong\n *   to the first statement).\n *\n * This function caches its result against the given sourceFile, since it is\n * needed both to find the module comment and to filter out module comments\n * node comments.\n */\nconst getModuleJSDocs = (typescript: TypeScript, sourceFile: ts.SourceFile) => {\n  let moduleJSDocs = moduleJSDocsMap.get(sourceFile);\n  if (moduleJSDocs !== undefined) {\n    return moduleJSDocs;\n  }\n  // Get the first child in the sourceFile; note that returning the first child\n  // from `ts.forEachChild` is more robust than `sourceFile.getChildAt(0)`,\n  // since `forEachChild` flattens embedded arrays that the child APIs would\n  // otherwise return.\n  const firstChild = typescript.forEachChild(sourceFile, (n) => n);\n  if (firstChild === undefined) {\n    moduleJSDocs = [];\n  } else {\n    // Get the JSDoc blocks attached to the first child (they oddly show up\n    // in the node's children)\n    const jsDocs = firstChild.getChildren().filter(typescript.isJSDoc);\n    // If there is more than one leading JSDoc block, grab all but the last,\n    // otherwise grab the one (see heuristic above)\n    moduleJSDocs = jsDocs.slice(0, jsDocs.length > 1 ? -1 : 1);\n    // If there is only one leading JSDoc block, it must have a module tag\n    if (jsDocs.length === 1 && !jsDocs[0].tags?.some(isModuleJSDocTag)) {\n      moduleJSDocs = [];\n    }\n  }\n  moduleJSDocsMap.set(sourceFile, moduleJSDocs!);\n  return moduleJSDocs;\n};\n\n/**\n * Parse summary, description, and deprecated information from JSDoc comments on\n * a given node.\n */\nexport const parseNodeJSDocInfo = (\n  node: ts.Node,\n  analyzer: AnalyzerInterface\n): DeprecatableDescribed => {\n  const info: DeprecatableDescribed = {};\n  const moduleJSDocs = getModuleJSDocs(\n    analyzer.typescript,\n    node.getSourceFile()\n  );\n  // Module-level docs (that are explicitly tagged as such) may be\n  // attached to the first declaration if the declaration is undocumented,\n  // so we filter those out since they shouldn't apply to a\n  // declaration node\n  const jsDocTags = analyzer.typescript\n    .getJSDocTags(node)\n    .filter(({parent}) => !moduleJSDocs.includes(parent as ts.JSDoc));\n  if (jsDocTags !== undefined) {\n    addJSDocTagInfo(info, jsDocTags, analyzer);\n  }\n  if (info.description === undefined) {\n    const comment = normalizeLineEndings(\n      node\n        .getChildren()\n        .filter(analyzer.typescript.isJSDoc)\n        .filter((c) => !moduleJSDocs.includes(c))\n        .map((n) => n.comment)\n        .filter((c) => c !== undefined)\n        .join('\\n')\n    );\n    if (comment.length > 0) {\n      info.description = comment;\n    }\n  }\n  return info;\n};\n\n/**\n * Parse summary, description, and deprecated information from JSDoc comments on\n * a given source file.\n */\nexport const parseModuleJSDocInfo = (\n  sourceFile: ts.SourceFile,\n  analyzer: AnalyzerInterface\n) => {\n  const moduleJSDocs = getModuleJSDocs(analyzer.typescript, sourceFile);\n  const info: DeprecatableDescribed = {};\n  addJSDocTagInfo(\n    info,\n    moduleJSDocs.flatMap((m) => m.tags ?? []),\n    analyzer\n  );\n  if (info.description === undefined) {\n    const comment = moduleJSDocs\n      .map((d) => d.comment)\n      .filter((c) => c !== undefined)\n      .join('\\n');\n    if (comment.length > 0) {\n      info.description = comment;\n    }\n  }\n  return info;\n};\n"]}

package/lib/javascript/mixins.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * @fileoverview
+ *
+ * Utilities for working with mixins
+ */
+import type ts from 'typescript';
+import { AnalyzerInterface, MixinDeclarationInit } from '../model.js';
+/**
+ * If the given variable declaration was a mixin function, returns a
+ * MixinDeclaration initialisation object, otherwise returns undefined.
+ *
+ * The mixin logic requires a few important syntactic heuristics to be met in
+ * order to be detected as a mixin:
+ *
+ * - a super class parameter (by any name) which is later used as a base class
+ * - a function body (rather than an arrow function)
+ * - an internal class which extends the previously mentioned super class parameter
+ * - a return statement returning the class
+ *
+ * For example:
+ *
+ * ```
+ * function MyMixin(superClass) {
+ *   class MixedClass extends superClass {
+ *     // ...
+ *   }
+ *   return MixedClass;
+ * }
+ * ```
+ *
+ * You can read more about this pattern in the TypeScript docs here:
+ * https://www.typescriptlang.org/docs/handbook/mixins.html
+ *
+ * If the function is unannotated and does not match the above mixin shape, it
+ * will silently just be analyzed as a simple function and not a mixin. However,
+ * the `@mixin` annotation can be added to produce specific diagnostic errors
+ * when a condition for being analyzed as a mixin is not met.
+ */
+export declare const maybeGetMixinFromFunctionLike: (fn: ts.FunctionLikeDeclaration, name: string, analyzer: AnalyzerInterface) => MixinDeclarationInit | undefined;
+//# sourceMappingURL=mixins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mixins.d.ts","sourceRoot":"","sources":["../../src/lib/javascript/mixins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAAC,iBAAiB,EAAE,oBAAoB,EAAC,MAAM,aAAa,CAAC;AA+BpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,6BAA6B,GACxC,IAAI,EAAE,CAAC,uBAAuB,EAC9B,MAAM,MAAM,EACZ,UAAU,iBAAiB,KAC1B,oBAAoB,GAAG,SAwHzB,CAAC"}

package/lib/javascript/mixins.js

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { getClassDeclaration } from './classes.js';
+import { createDiagnostic } from '../errors.js';
+import { DiagnosticCode } from '../diagnostic-code.js';
+import { getSymbolForName } from '../references.js';
+const nodeHasMixinHint = (node, analyzer) => analyzer.typescript
+    .getJSDocTags(node)
+    .some((tag) => tag.tagName.text === 'mixin');
+const addDiagnosticIfMixin = (node, hasMixinHint, message, analyzer) => {
+    if (hasMixinHint) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node,
+            message,
+            code: DiagnosticCode.UNSUPPORTED,
+            category: analyzer.typescript.DiagnosticCategory.Warning,
+        }));
+    }
+    return undefined;
+};
+/**
+ * If the given variable declaration was a mixin function, returns a
+ * MixinDeclaration initialisation object, otherwise returns undefined.
+ *
+ * The mixin logic requires a few important syntactic heuristics to be met in
+ * order to be detected as a mixin:
+ *
+ * - a super class parameter (by any name) which is later used as a base class
+ * - a function body (rather than an arrow function)
+ * - an internal class which extends the previously mentioned super class parameter
+ * - a return statement returning the class
+ *
+ * For example:
+ *
+ * ```
+ * function MyMixin(superClass) {
+ *   class MixedClass extends superClass {
+ *     // ...
+ *   }
+ *   return MixedClass;
+ * }
+ * ```
+ *
+ * You can read more about this pattern in the TypeScript docs here:
+ * https://www.typescriptlang.org/docs/handbook/mixins.html
+ *
+ * If the function is unannotated and does not match the above mixin shape, it
+ * will silently just be analyzed as a simple function and not a mixin. However,
+ * the `@mixin` annotation can be added to produce specific diagnostic errors
+ * when a condition for being analyzed as a mixin is not met.
+ */
+export const maybeGetMixinFromFunctionLike = (fn, name, analyzer) => {
+    const hasMixinHint = nodeHasMixinHint(fn, analyzer);
+    if (fn.parameters === undefined || fn.parameters.length < 1) {
+        addDiagnosticIfMixin(fn, hasMixinHint, `Expected mixin to have a superClass parameter.`, analyzer);
+        return undefined;
+    }
+    const functionBody = fn.body;
+    if (functionBody === undefined) {
+        addDiagnosticIfMixin(fn, hasMixinHint, `Expected mixin to have a block function body.`, analyzer);
+        return undefined;
+    }
+    let classDeclaration;
+    let returnStatement;
+    if (analyzer.typescript.isBlock(functionBody)) {
+        for (const s of functionBody.statements) {
+            if (analyzer.typescript.isClassDeclaration(s)) {
+                classDeclaration = s;
+            }
+            if (analyzer.typescript.isReturnStatement(s)) {
+                returnStatement = s;
+                if (classDeclaration === undefined &&
+                    s.expression !== undefined &&
+                    analyzer.typescript.isClassLike(s.expression)) {
+                    classDeclaration = s.expression;
+                }
+            }
+        }
+        if (returnStatement === undefined) {
+            addDiagnosticIfMixin(fn, hasMixinHint, `Expected mixin to contain a return statement returning a class.`, analyzer);
+            return undefined;
+        }
+    }
+    else if (analyzer.typescript.isClassLike(functionBody)) {
+        classDeclaration = functionBody;
+    }
+    if (classDeclaration === undefined) {
+        addDiagnosticIfMixin(fn, hasMixinHint, `Expected mixin to contain a class declaration statement.`, analyzer);
+        return undefined;
+    }
+    const extendsClause = classDeclaration.heritageClauses?.find((c) => c.token === analyzer.typescript.SyntaxKind.ExtendsKeyword);
+    if (extendsClause === undefined) {
+        addDiagnosticIfMixin(fn, hasMixinHint, `Expected mixin to contain class declaration extending a superClass argument to function.`, analyzer);
+        return undefined;
+    }
+    if (extendsClause.types.length !== 1) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: extendsClause,
+            message: 'Internal error: did not expect a mixin class extends clause to have multiple types',
+            code: DiagnosticCode.UNSUPPORTED,
+            category: analyzer.typescript.DiagnosticCategory.Warning,
+        }));
+        return undefined;
+    }
+    const superClassArgIndex = findSuperClassArgIndexFromHeritage(fn, extendsClause.types[0].expression, analyzer);
+    if (superClassArgIndex < 0) {
+        analyzer.addDiagnostic(createDiagnostic({
+            typescript: analyzer.typescript,
+            node: extendsClause,
+            message: 'Did not find a "superClass" argument used in the extends clause of mixin class.',
+            code: DiagnosticCode.UNSUPPORTED,
+            category: analyzer.typescript.DiagnosticCategory.Warning,
+        }));
+        return undefined;
+    }
+    const classDeclarationName = classDeclaration.name?.text ?? name;
+    return {
+        node: fn,
+        name,
+        superClassArgIndex,
+        classDeclaration: getClassDeclaration(classDeclaration, classDeclarationName, analyzer, undefined, true /* isMixinClass */),
+    };
+};
+const findSuperClassArgIndexFromHeritage = (mixinFunction, expression, analyzer) => {
+    if (analyzer.typescript.isIdentifier(expression)) {
+        const paramSymbol = getSymbolForName(expression.text, expression, analyzer);
+        if (paramSymbol?.declarations) {
+            const paramDecl = paramSymbol.declarations;
+            return mixinFunction.parameters.findIndex((param) => paramDecl.includes(param));
+        }
+    }
+    else if (analyzer.typescript.isCallExpression(expression)) {
+        for (const arg of expression.arguments) {
+            const index = findSuperClassArgIndexFromHeritage(mixinFunction, arg, analyzer);
+            if (index >= 0) {
+                return index;
+            }
+        }
+    }
+    return -1;
+};
+//# sourceMappingURL=mixins.js.map

package/lib/javascript/mixins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixins.js","sourceRoot":"","sources":["../../src/lib/javascript/mixins.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * @license\n * Copyright 2024 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/**\n * @fileoverview\n *\n * Utilities for working with mixins\n */\n\nimport type ts from 'typescript';\nimport {AnalyzerInterface, MixinDeclarationInit} from '../model.js';\nimport {getClassDeclaration} from './classes.js';\nimport {createDiagnostic} from '../errors.js';\nimport {DiagnosticCode} from '../diagnostic-code.js';\nimport {getSymbolForName} from '../references.js';\n\nconst nodeHasMixinHint = (node: ts.Node, analyzer: AnalyzerInterface) =>\n  analyzer.typescript\n    .getJSDocTags(node)\n    .some((tag) => tag.tagName.text === 'mixin');\n\nconst addDiagnosticIfMixin = (\n  node: ts.Node,\n  hasMixinHint: boolean,\n  message: string,\n  analyzer: AnalyzerInterface\n) => {\n  if (hasMixinHint) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node,\n        message,\n        code: DiagnosticCode.UNSUPPORTED,\n        category: analyzer.typescript.DiagnosticCategory.Warning,\n      })\n    );\n  }\n  return undefined;\n};\n\n/**\n * If the given variable declaration was a mixin function, returns a\n * MixinDeclaration initialisation object, otherwise returns undefined.\n *\n * The mixin logic requires a few important syntactic heuristics to be met in\n * order to be detected as a mixin:\n *\n * - a super class parameter (by any name) which is later used as a base class\n * - a function body (rather than an arrow function)\n * - an internal class which extends the previously mentioned super class parameter\n * - a return statement returning the class\n *\n * For example:\n *\n * ```\n * function MyMixin(superClass) {\n *   class MixedClass extends superClass {\n *     // ...\n *   }\n *   return MixedClass;\n * }\n * ```\n *\n * You can read more about this pattern in the TypeScript docs here:\n * https://www.typescriptlang.org/docs/handbook/mixins.html\n *\n * If the function is unannotated and does not match the above mixin shape, it\n * will silently just be analyzed as a simple function and not a mixin. However,\n * the `@mixin` annotation can be added to produce specific diagnostic errors\n * when a condition for being analyzed as a mixin is not met.\n */\nexport const maybeGetMixinFromFunctionLike = (\n  fn: ts.FunctionLikeDeclaration,\n  name: string,\n  analyzer: AnalyzerInterface\n): MixinDeclarationInit | undefined => {\n  const hasMixinHint = nodeHasMixinHint(fn, analyzer);\n  if (fn.parameters === undefined || fn.parameters.length < 1) {\n    addDiagnosticIfMixin(\n      fn,\n      hasMixinHint,\n      `Expected mixin to have a superClass parameter.`,\n      analyzer\n    );\n    return undefined;\n  }\n  const functionBody = fn.body;\n  if (functionBody === undefined) {\n    addDiagnosticIfMixin(\n      fn,\n      hasMixinHint,\n      `Expected mixin to have a block function body.`,\n      analyzer\n    );\n    return undefined;\n  }\n  let classDeclaration: ts.ClassLikeDeclaration | undefined;\n  let returnStatement: ts.ReturnStatement | undefined;\n  if (analyzer.typescript.isBlock(functionBody)) {\n    for (const s of functionBody.statements) {\n      if (analyzer.typescript.isClassDeclaration(s)) {\n        classDeclaration = s;\n      }\n      if (analyzer.typescript.isReturnStatement(s)) {\n        returnStatement = s;\n\n        if (\n          classDeclaration === undefined &&\n          s.expression !== undefined &&\n          analyzer.typescript.isClassLike(s.expression)\n        ) {\n          classDeclaration = s.expression;\n        }\n      }\n    }\n\n    if (returnStatement === undefined) {\n      addDiagnosticIfMixin(\n        fn,\n        hasMixinHint,\n        `Expected mixin to contain a return statement returning a class.`,\n        analyzer\n      );\n      return undefined;\n    }\n  } else if (analyzer.typescript.isClassLike(functionBody)) {\n    classDeclaration = functionBody;\n  }\n  if (classDeclaration === undefined) {\n    addDiagnosticIfMixin(\n      fn,\n      hasMixinHint,\n      `Expected mixin to contain a class declaration statement.`,\n      analyzer\n    );\n    return undefined;\n  }\n  const extendsClause = classDeclaration.heritageClauses?.find(\n    (c) => c.token === analyzer.typescript.SyntaxKind.ExtendsKeyword\n  );\n  if (extendsClause === undefined) {\n    addDiagnosticIfMixin(\n      fn,\n      hasMixinHint,\n      `Expected mixin to contain class declaration extending a superClass argument to function.`,\n      analyzer\n    );\n    return undefined;\n  }\n  if (extendsClause.types.length !== 1) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: extendsClause,\n        message:\n          'Internal error: did not expect a mixin class extends clause to have multiple types',\n        code: DiagnosticCode.UNSUPPORTED,\n        category: analyzer.typescript.DiagnosticCategory.Warning,\n      })\n    );\n    return undefined;\n  }\n  const superClassArgIndex = findSuperClassArgIndexFromHeritage(\n    fn,\n    extendsClause.types[0].expression,\n    analyzer\n  );\n  if (superClassArgIndex < 0) {\n    analyzer.addDiagnostic(\n      createDiagnostic({\n        typescript: analyzer.typescript,\n        node: extendsClause,\n        message:\n          'Did not find a \"superClass\" argument used in the extends clause of mixin class.',\n        code: DiagnosticCode.UNSUPPORTED,\n        category: analyzer.typescript.DiagnosticCategory.Warning,\n      })\n    );\n    return undefined;\n  }\n\n  const classDeclarationName = classDeclaration.name?.text ?? name;\n\n  return {\n    node: fn,\n    name,\n    superClassArgIndex,\n    classDeclaration: getClassDeclaration(\n      classDeclaration,\n      classDeclarationName,\n      analyzer,\n      undefined,\n      true /* isMixinClass */\n    ),\n  };\n};\n\nconst findSuperClassArgIndexFromHeritage = (\n  mixinFunction: ts.FunctionLikeDeclaration,\n  expression: ts.Expression,\n  analyzer: AnalyzerInterface\n): number => {\n  if (analyzer.typescript.isIdentifier(expression)) {\n    const paramSymbol = getSymbolForName(expression.text, expression, analyzer);\n\n    if (paramSymbol?.declarations) {\n      const paramDecl = paramSymbol.declarations;\n      return mixinFunction.parameters.findIndex((param) =>\n        paramDecl.includes(param)\n      );\n    }\n  } else if (analyzer.typescript.isCallExpression(expression)) {\n    for (const arg of expression.arguments) {\n      const index = findSuperClassArgIndexFromHeritage(\n        mixinFunction,\n        arg,\n        analyzer\n      );\n      if (index >= 0) {\n        return index;\n      }\n    }\n  }\n  return -1;\n};\n"]}

package/lib/javascript/modules.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * @fileoverview
+ *
+ * Utilities for analyzing ES modules
+ */
+import type ts from 'typescript';
+import { Module, AnalyzerInterface, PackageInfo, Declaration, ModuleInfo } from '../model.js';
+import { AbsolutePath } from '../paths.js';
+export type TypeScript = typeof ts;
+/**
+ * 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 declare const getModuleInfo: (modulePath: AbsolutePath, analyzer: AnalyzerInterface, packageInfo?: PackageInfo) => ModuleInfo;
+/**
+ * Returns an analyzer `Module` model for the given module path.
+ */
+export declare const getModule: (modulePath: AbsolutePath, analyzer: AnalyzerInterface, packageInfo?: PackageInfo) => Module;
+/**
+ * Resolves a module specifier expression node to an absolute path on disk.
+ */
+export declare const getPathForModuleSpecifierExpression: (specifierExpression: ts.Expression, analyzer: AnalyzerInterface) => AbsolutePath | undefined;
+/**
+ * Resolve a module specifier to an absolute path on disk.
+ */
+export declare const getPathForModuleSpecifier: (specifier: string, location: ts.Node, analyzer: AnalyzerInterface) => AbsolutePath | undefined;
+/**
+ * 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 declare const getResolvedExportFromSourcePath: (modulePath: AbsolutePath, name: string, analyzer: AnalyzerInterface) => Declaration;
+//# sourceMappingURL=modules.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../../src/lib/javascript/modules.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EACL,MAAM,EACN,iBAAiB,EACjB,WAAW,EACX,WAAW,EAIX,UAAU,EAEX,MAAM,aAAa,CAAC;AAOrB,OAAO,EAAC,YAAY,EAAiC,MAAM,aAAa,CAAC;AAWzE,MAAM,MAAM,UAAU,GAAG,OAAO,EAAE,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,YAAY,YAAY,EACxB,UAAU,iBAAiB,EAC3B,cAAa,WAAkD,KAC9D,UAuBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,YAAY,YAAY,EACxB,UAAU,iBAAiB,EAC3B,cAAa,WAAkD,WAiHhE,CAAC;AA6IF;;GAEG;AACH,eAAO,MAAM,mCAAmC,GAC9C,qBAAqB,EAAE,CAAC,UAAU,EAClC,UAAU,iBAAiB,KAC1B,YAAY,GAAG,SAGjB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACpC,WAAW,MAAM,EACjB,UAAU,EAAE,CAAC,IAAI,EACjB,UAAU,iBAAiB,KAC1B,YAAY,GAAG,SAmBjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAC1C,YAAY,YAAY,EACxB,MAAM,MAAM,EACZ,UAAU,iBAAiB,gBACgC,CAAC"}