@ui5/webcomponents-tools 0.0.0-037d08c67

package/lib/cem/event.mjs

@@ -0,0 +1,168 @@
+import { parse } from "comment-parser";
+import {
+	getPrivacyStatus,
+	getDeprecatedStatus,
+	getSinceStatus,
+	getType,
+	getTypeRefs,
+	validateJSDocComment,
+	hasTag,
+	findTag,
+	findAllTags,
+	getReference,
+	normalizeDescription,
+	normalizeTagType,
+	logDocumentationError
+} from "./utils.mjs";
+
+const jsDocRegExp = /\/\*\*(.|\n)+?\s+\*\//;
+const ASTFalseKeywordCode = 94;
+
+const getParams = (ts, eventDetails, commentParams, classNode, moduleDoc) => {
+	return commentParams?.map(commentParam => {
+		const { typeName, name } = getType(normalizeTagType(commentParam?.type));
+		let type;
+
+		if (typeName) {
+			type = { text: typeName };
+
+			let typeRefs = name?.split("|")
+				?.map(e => getReference(ts, e.trim(), classNode, moduleDoc.path))
+				.filter(Boolean);
+
+			if (typeRefs?.length) {
+				type.references = typeRefs;
+			}
+		}
+
+		return {
+			type,
+			name: commentParam?.name,
+			_ui5privacy: "public",
+			description: normalizeDescription(commentParam?.description),
+		};
+	});
+};
+
+function processEvent(ts, event, classNode, moduleDoc) {
+	const name = event?.expression?.arguments?.[0]?.text;
+	const result = {
+		name,
+		_ui5privacy: "private",
+		type: { text: "CustomEvent" }
+	};
+
+	const comment = event.getFullText?.().match(jsDocRegExp)?.[0];
+
+	if (!comment) {
+		return result;
+	}
+
+	const eventParsedComment = parse(comment, { spacing: 'preserve' })[0];
+
+	validateJSDocComment("event", eventParsedComment, name, moduleDoc);
+
+	const deprecatedTag = findTag(eventParsedComment, "deprecated");
+	const privacy = findTag(eventParsedComment, ["public", "private", "protected"])?.tag || "private";
+	const sinceTag = findTag(eventParsedComment, "since");
+	const commentParams = findAllTags(eventParsedComment, "param");
+	const description = normalizeDescription(eventParsedComment?.description);
+	const native = hasTag(eventParsedComment, "native");
+	const eventArgs = event?.expression?.arguments;
+	let eventBubbles;
+	let eventCancelable;
+	let eventDetails;
+
+	eventArgs && eventArgs.forEach(arg => {
+		arg.properties?.forEach(prop => {
+			if (prop.name?.text === "bubbles") {
+				eventBubbles = prop.initializer.kind === ASTFalseKeywordCode ? false : true;
+			} else if (prop.name?.text === "cancelable") {
+				eventCancelable = prop.initializer.kind === ASTFalseKeywordCode ? false : true;
+			} else if (prop.name?.text === "detail") {
+				eventDetails = prop.initializer?.properties;
+			}
+		});
+	});
+
+	result.description = description;
+	result._ui5Cancelable = eventCancelable !== undefined ? eventCancelable : false;
+	result._ui5allowPreventDefault = result._ui5Cancelable;
+	result._ui5Bubbles = eventBubbles !== undefined ? eventBubbles : false;
+
+	if (native) {
+		result.type = { text: "Event" };
+	}
+
+	if (privacy) {
+		result._ui5privacy = privacy;
+	}
+
+	if (deprecatedTag?.name) {
+		result.deprecated = deprecatedTag.description
+			? `${deprecatedTag.name} ${deprecatedTag.description}`
+			: deprecatedTag.name;
+	} else if (deprecatedTag) {
+		result.deprecated = true;
+	}
+
+	if (sinceTag?.name) {
+		result._ui5since = sinceTag?.description
+			? `${sinceTag.name} ${sinceTag.description}`
+			: sinceTag.name;
+	}
+
+	const eventDetailType = classNode.members?.find(member => {
+		return ts.isPropertyDeclaration(member) && member.name.text === "eventDetails"
+	})?.type;
+	const eventDetailRef = eventDetailType?.members?.find(member => member.name.text === name) || eventDetailType?.types?.[eventDetailType?.types?.length - 1]?.members?.find(member => member.name.text === name);
+	const hasGeneric = !!event?.expression?.typeArguments
+
+	if (commentParams.length) {
+		if (eventDetailRef && hasGeneric) {
+			logDocumentationError(moduleDoc.path, `Event details for event '${name}' has to be defined either with generic or with eventDetails.`)
+		} else if (eventDetails) {
+			if (hasGeneric) {
+				const typesText = event?.expression?.typeArguments.map(type => type.typeName?.text).filter(Boolean).join(" | ");
+				const typeRefs = (getTypeRefs(ts, event.expression)
+					?.map(e => getReference(ts, e, event, moduleDoc.path)).filter(Boolean)) || [];
+
+				result.type = { text: `CustomEvent<${typesText}>` };
+
+				if (typeRefs.length) {
+					result.type.references = typeRefs;
+				}
+			} else if (eventDetailRef) {
+				const typesText = eventDetailRef?.type?.typeName?.text;
+				const typeRefs = (getTypeRefs(ts, eventDetailRef)
+					?.map(e => getReference(ts, e, event, moduleDoc.path)).filter(Boolean)) || [];
+
+				result.type = { text: `CustomEvent<${typesText}>` };
+
+				if (typeRefs.length) {
+					result.type.references = typeRefs;
+				}
+			} else {
+				logDocumentationError(moduleDoc.path, `Event details for event '${name}' must be described using generics. Add type via generics to the decorator: @event<TypeForDetails>("${name}", {details}).`)
+			}
+		} else if (eventDetailRef) {
+			const typesText = eventDetailRef?.type?.typeName?.text;
+			const typeRefs = (getTypeRefs(ts, eventDetailRef)
+				?.map(e => getReference(ts, e, event, moduleDoc.path)).filter(Boolean)) || [];
+
+			result.type = { text: `CustomEvent<${typesText}>` };
+
+			if (typeRefs.length) {
+				result.type.references = typeRefs;
+			}
+		} else {
+			logDocumentationError(moduleDoc.path, `Event details for event '${name}' must be described.`)
+		}
+
+		result._ui5parameters = getParams(ts, eventDetails, commentParams, classNode, moduleDoc);
+	}
+
+	return result;
+}
+
+export default processEvent;

package/lib/cem/patch/@custom-elements-manifest/analyzer/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import ts from 'typescript';
+import path from 'path';
+// Patch: Custom patch to not merge child parent privacy/type
+// https://github.com/open-wc/custom-elements-manifest/pull/300
+import { globby } from 'globby';
+import fs from 'fs';
+import commandLineArgs from 'command-line-args';
+import chokidar from 'chokidar';
+import debounce from 'debounce';
+
+import { create } from './src/create.js';
+import {
+  getUserConfig,
+  getCliConfig,
+  addFrameworkPlugins,
+  addCustomElementsPropertyToPackageJson,
+  mergeGlobsAndExcludes,
+  timestamp,
+  DEFAULTS,
+  MENU,
+} from './src/utils/cli-helpers.js';
+import { findExternalManifests } from './src/utils/find-external-manifests.js';
+
+/**
+ * @param {{argv:string[]; cwd: string; noWrite:boolean}} [opts]
+ */
+export async function cli({ argv = process.argv, cwd = process.cwd(), noWrite } = {}) {
+  const mainDefinitions = [{ name: 'command', defaultOption: true }];
+  const mainOptions = commandLineArgs(mainDefinitions, { stopAtFirstUnknown: true, argv });
+  const cliArgs = mainOptions._unknown || [];
+
+  if (mainOptions.command === 'analyze') {
+    const { config: configPath, ...cliConfig } = getCliConfig(cliArgs);
+    const userConfig = await getUserConfig(configPath, cwd);
+
+    /**
+     * Merged config options
+     * Command line options override userConfig options
+     */
+    const mergedOptions = { ...DEFAULTS, ...userConfig, ...cliConfig };
+    const merged = mergeGlobsAndExcludes(DEFAULTS, userConfig, cliConfig);
+    async function run() {
+      const globs = await globby(merged, { cwd });
+      const modules = userConfig?.overrideModuleCreation
+        ? userConfig.overrideModuleCreation({ ts, globs })
+        : globs.map((glob) => {
+            const fullPath = path.resolve(cwd, glob);
+            const source = fs.readFileSync(fullPath).toString();
+
+            return ts.createSourceFile(glob, source, ts.ScriptTarget.ES2015, true);
+          });
+
+      let thirdPartyCEMs = [];
+      if (mergedOptions?.dependencies) {
+        try {
+          const fullPathGlobs = globs.map(glob => path.resolve(cwd, glob));
+          thirdPartyCEMs = await findExternalManifests(fullPathGlobs, {basePath: cwd});
+        } catch (e) {
+          if (mergedOptions.dev) console.log(`Failed to add third party CEMs. \n\n${e.stack}`);
+        }
+      }
+
+      let plugins = await addFrameworkPlugins(mergedOptions);
+      plugins = [...plugins, ...(userConfig?.plugins || [])];
+
+      const context = { dev: mergedOptions.dev, thirdPartyCEMs };
+
+      /**
+       * Create the manifest
+       */
+       const customElementsManifest = create({modules, plugins, context});
+
+       if (mergedOptions.dev) {
+        console.log(JSON.stringify(customElementsManifest, null, 2));
+      }
+
+      if(!noWrite) {
+        const outdir = path.join(cwd, mergedOptions.outdir);
+        if (!fs.existsSync(outdir)) {
+          fs.mkdirSync(outdir, { recursive: true });
+        }
+        fs.writeFileSync(
+          path.join(outdir, 'custom-elements.json'),
+          `${JSON.stringify(customElementsManifest, null, 2)}\n`,
+        );
+       }
+
+      if (!mergedOptions.quiet) {
+        console.log(`[${timestamp()}] @custom-elements-manifest/analyzer: Created new manifest.`);
+      }
+
+      return customElementsManifest;
+    }
+    /** The manifest that will be returned for programmatic calls of cli */
+    const manifest = await run();
+
+    /**
+     * Watch mode
+     */
+    if (mergedOptions.watch) {
+      const fileWatcher = chokidar.watch(merged);
+
+      const onChange = debounce(run, 100);
+
+      fileWatcher.addListener('add', onChange);
+      fileWatcher.addListener('change', onChange);
+      fileWatcher.addListener('unlink', onChange);
+    }
+
+    try {
+      if (mergedOptions.packagejson) {
+        addCustomElementsPropertyToPackageJson(mergedOptions.outdir);
+      }
+    } catch {
+      console.log(
+        `Could not add 'customElements' property to ${cwd}${
+          path.sep
+        }package.json. \nAdding this property helps tooling locate your Custom Elements Manifest. Please consider adding it yourself, or file an issue if you think this is a bug.\nhttps://www.github.com/open-wc/custom-elements-manifest`,
+      );
+    }
+
+    return manifest;
+  } else {
+    console.log(MENU);
+  }
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@custom-elements-manifest/analyzer",
+  "version": "0.10.10",
+  "description": "",
+  "license": "MIT",
+  "type": "module",
+  "types": "index.d.ts",
+  "bin": {
+    "custom-elements-manifest": "./cem.js",
+    "cem": "./cem.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-wc/custom-elements-manifest.git",
+    "directory": "packages/analyzer"
+  },
+  "author": "open-wc",
+  "homepage": "https://github.com/open-wc/custom-elements-manifest",
+  "bugs": {
+    "url": "https://github.com/open-wc/custom-elements-manifest"
+  },
+  "main": "index.js",
+  "scripts": {
+    "prepublishOnly": "npm test && npm run build:browser",
+    "start": "nodemon --ignore './custom-elements.json' cem.js analyze --dev --fast",
+    "test": "asdgf",
+    "build:browser": "esbuild src/browser-entrypoint.js --bundle --format=esm --outfile=browser/index.js",
+    "test:watch": "watchexec -w src -w test npm test",
+    "update-fixtures": "node scripts/update-version.js --version 1.0.0"
+  },
+  "keywords": [
+    "custom-elements",
+    "custom-elements-json",
+    "custom-elements-manifest",
+    "customelements",
+    "webcomponents",
+    "customelementsjson",
+    "customelementsmanifest"
+  ],
+  "dependencies": {
+    "@custom-elements-manifest/find-dependencies": "^0.0.6",
+    "@github/catalyst": "^1.6.0",
+    "@web/config-loader": "0.1.3",
+    "chokidar": "3.5.2",
+    "command-line-args": "5.1.2",
+    "comment-parser": "1.2.4",
+    "custom-elements-manifest": "1.0.0",
+    "debounce": "1.2.1",
+    "globby": "11.0.4",
+    "typescript": "~5.4.2"
+  },
+  "devDependencies": {},
+  "contributors": [
+    "Pascal Schilp <pascalschilp@gmail.com>",
+    "Benny Powers <web@bennypowers.com>",
+    "Matias Huhta <huhta.matias@gmail.com>"
+  ],
+  "customElements": "custom-elements.json"
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/browser-entrypoint.js

@@ -0,0 +1,23 @@
+/**
+ * This file is the entrypoint for rollup to correctly bundle the analyzer for the browser.
+ * Do not use directly, but import from ./browser/index.js
+ */
+
+import ts from 'typescript';
+
+import { create } from './create.js';
+import { catalystPlugin } from './features/framework-plugins/catalyst/catalyst.js';
+import { catalystPlugin2 } from './features/framework-plugins/catalyst-major-2/catalyst.js';
+import { stencilPlugin } from './features/framework-plugins/stencil/stencil.js';
+import { litPlugin } from './features/framework-plugins/lit/lit.js';
+import { fastPlugin } from './features/framework-plugins/fast/fast.js';
+
+export { 
+  ts,
+  create,
+  catalystPlugin,
+  catalystPlugin2,
+  stencilPlugin,
+  litPlugin,
+  fastPlugin
+};

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/create.js

@@ -0,0 +1,117 @@
+import ts from 'typescript';
+import { FEATURES } from './features/index.js';
+import { withErrorHandling } from './utils/index.js';
+
+/**
+ * CORE
+ *
+ * This function is the core of the analyzer. It takes an array of ts sourceFiles, and creates a
+ * custom elements manifest.
+ */
+export function create({modules, plugins = [], context = {dev:false}}) {
+  const customElementsManifest = {
+    schemaVersion: '1.0.0',
+    readme: '',
+    modules: [],
+  };
+
+  const { dev } = context;
+
+  const mergedPlugins = [
+    ...FEATURES,
+    ...plugins,
+  ];
+
+  if(dev) console.log('[INITIALIZE PLUGINS]');
+  mergedPlugins.forEach(({name, initialize}) => {
+    withErrorHandling(name, () => {
+      initialize?.({ts, customElementsManifest, context});
+    });
+  });
+
+  modules.forEach(currModule => {
+    if(dev) console.log('[COLLECT PHASE]: ', currModule.fileName);
+    /**
+     * COLLECT PHASE
+     * First pass through all modules. Can be used to gather imports, exports, types, default values,
+     * which you may need to know the existence of in a later phase.
+     */
+    collect(currModule, context, mergedPlugins);
+  });
+
+  modules.forEach(currModule => {
+    if(dev) console.log('[ANALYZE PHASE]: ', currModule.fileName);
+    const moduleDoc = {
+      kind: "javascript-module",
+      path: currModule.fileName,
+      declarations: [],
+      exports: []
+    };
+
+    /**
+     * ANALYZE PHASE
+     * Go through the AST of every separate module, and gather as much as information as we can
+     * This includes a modules imports, which are not specified in custom-elements.json, but are
+     * required for the LINK PHASE, and deleted when processed
+     */
+    analyze(currModule, moduleDoc, context, mergedPlugins);
+    customElementsManifest.modules.push(moduleDoc);
+
+    if(dev) console.log('[MODULE LINK PHASE]: ', currModule.fileName);
+    /**
+     * LINK PHASE
+     * All information for a module has been gathered, now we can link information together. Like:
+     * - Finding a CustomElement's tagname by finding its customElements.define() call (or 'export')
+     * - Applying inheritance to classes (adding `inheritedFrom` properties/attrs/events/methods)
+     */
+    mergedPlugins.forEach(({name, moduleLinkPhase}) => {
+      withErrorHandling(name, () => {
+        moduleLinkPhase?.({ts, moduleDoc, context});
+      });
+    });
+  });
+
+  if(dev) console.log('[PACKAGE LINK PHASE]');
+  /**
+   * PACKAGE LINK PHASE
+   * All modules have now been parsed, we can now link information from across modules together
+   * - Link classes to their definitions etc
+   * - Match tagNames for classDocs
+   * - Apply inheritance
+   */
+  mergedPlugins.forEach(({name, packageLinkPhase}) => {
+    withErrorHandling(name, () => {
+      packageLinkPhase?.({customElementsManifest, context});
+    });
+  });
+
+  return customElementsManifest;
+}
+
+function collect(source, context, mergedPlugins) {
+  visitNode(source);
+
+  function visitNode(node) {
+    mergedPlugins.forEach(({name, collectPhase}) => {
+      withErrorHandling(name, () => {
+        collectPhase?.({ts, node, context});
+      });
+    });
+
+    ts.forEachChild(node, visitNode);
+  }
+}
+
+function analyze(source, moduleDoc, context, mergedPlugins) {
+  visitNode(source);
+
+  function visitNode(node) {
+    mergedPlugins.forEach(({name, analyzePhase}) => {
+      withErrorHandling(name, () => {
+        analyzePhase?.({ts, node, moduleDoc, context});
+      });
+    });
+
+    ts.forEachChild(node, visitNode);
+  }
+}

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/features/analyse-phase/arrow-function.js

@@ -0,0 +1,26 @@
+import { hasInitializer } from '../../utils/ast-helpers.js';
+import { isMixin } from '../../utils/mixins.js';
+import { createArrowFunction } from './creators/createArrowFunction.js';
+
+
+/**
+ * arrowFunctionPlugin
+ * 
+ * handles arrow functions
+ */
+export function arrowFunctionPlugin() {
+  return {
+    name: 'CORE - ARROW-FUNCTION',
+    analyzePhase({ts, node, moduleDoc}){
+      switch(node.kind) {
+        case ts.SyntaxKind.VariableStatement:
+          if(!isMixin(node) && hasInitializer(node)) {
+            const functionLike = createArrowFunction(node);
+            moduleDoc.declarations.push(functionLike);
+          }
+          break;
+      }
+    }
+  }
+}
+

package/lib/cem/patch/@custom-elements-manifest/analyzer/src/features/analyse-phase/class-jsdoc.js

@@ -0,0 +1,157 @@
+import { parse } from 'comment-parser';
+import { handleJsDocType, normalizeDescription } from '../../utils/jsdoc.js';
+import { has, safe } from '../../utils/index.js';
+
+/**
+ * CLASS-JSDOC
+ *
+ * Deals with any JSDoc above a class
+ */
+export function classJsDocPlugin() {
+  return {
+    name: 'CORE - CLASS-JSDOC',
+    analyzePhase({ts, node, moduleDoc}){
+      switch (node.kind) {
+        case ts.SyntaxKind.ClassDeclaration:
+          const className = node?.name?.getText();
+          const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
+
+          /**
+           * Because we use a bunch of 'non-standard' JSDoc annotations, TS doesn't recognize most of them.
+           * Instead we use `comment-parser` to parse the JSDoc.
+           *
+           * Loops through each JSDoc (yes, there can be multiple) above a class, and parses every JSDoc annotation
+           *
+           * Checks to see if the item is already in the classDoc, and if so merge and overwrite (JSDoc takes precedence)
+           */
+          node?.jsDoc?.forEach(jsDoc => {
+            const parsed = parse(jsDoc?.getFullText());
+            parsed?.forEach(parsedJsDoc => {
+
+              /**
+               * If any of the tags is a `@typedef`, we ignore it; this JSDoc comment may be above a class,
+               * it probably doesnt _belong_ to the class, but something else in the file
+               */
+              if(parsedJsDoc?.tags?.some(tag => tag?.tag === 'typedef')) return;
+
+              parsedJsDoc?.tags?.forEach(jsDoc => {
+                switch(jsDoc.tag) {
+                  case 'attr':
+                  case 'attribute':
+                    const attributeAlreadyExists = classDoc?.attributes?.find(attr => attr.name === jsDoc.name);
+                    let attributeDoc = attributeAlreadyExists || {};
+                    attributeDoc = handleClassJsDoc(attributeDoc, jsDoc);
+                    if(!attributeAlreadyExists) {
+                      classDoc.attributes.push(attributeDoc);
+                    }
+                    break;
+                  case 'prop':
+                  case 'property':
+                    const fieldAlreadyExists = classDoc?.members?.find(member => member.name === jsDoc.name);
+                    let fieldDoc = fieldAlreadyExists || {};
+                    fieldDoc = handleClassJsDoc(fieldDoc, jsDoc);
+                    fieldDoc.kind = 'field';
+                    if(!fieldAlreadyExists) {
+                      classDoc.members.push(fieldDoc);
+                    }
+                    break;
+                  case 'fires':
+                  case 'event':
+                    const eventAlreadyExists = classDoc?.events?.find(event => event.name === jsDoc.name);
+                    let eventDoc = eventAlreadyExists || {};
+                    eventDoc = handleClassJsDoc(eventDoc, jsDoc);
+                    delete eventDoc.privacy;
+                    if(!eventAlreadyExists) {
+                      classDoc.events.push(eventDoc);
+                    }
+                    break;
+                  case 'csspart':
+                  case 'part':
+                    let cssPartDoc = {};
+                    cssPartDoc = handleClassJsDoc(cssPartDoc, jsDoc);
+                    classDoc.cssParts.push(cssPartDoc);
+                    break;
+                  case 'cssprop':
+                  case 'cssproperty':
+                    let cssPropertyDoc = {};
+                    cssPropertyDoc = handleClassJsDoc(cssPropertyDoc, jsDoc);
+                    classDoc.cssProperties.push(cssPropertyDoc);
+                    break;
+                  case 'slot':
+                    let slotDoc = {};
+                    slotDoc = handleClassJsDoc(slotDoc, jsDoc);
+                    classDoc.slots.push(slotDoc);
+                    break;
+                  case 'tag':
+                  case 'tagname':
+                  case 'element':
+                  case 'customElement':
+                  case 'customelement':
+                    classDoc.tagName = jsDoc?.name || '';
+                    classDoc.customElement = true;
+                    break;
+                  case 'cssState':
+                  case 'cssstate':
+                    let statePropertyDoc = {};
+                    statePropertyDoc = handleClassJsDoc(statePropertyDoc, jsDoc);
+                    classDoc.cssStates.push(statePropertyDoc);
+                    break;
+                  case 'deprecated':
+                    classDoc.deprecated = jsDoc?.name ? `${jsDoc.name} ${jsDoc?.description}`.trim() : "true";
+                    break;
+                }
+              })
+            });
+
+            /**
+             * Description
+             */
+            if(jsDoc?.comment) {
+              if(has(jsDoc?.comment)) {
+                classDoc.description = jsDoc.comment.map(com => `${safe(() => com?.name?.getText()) ?? ''}${com.text}`).join('');
+              } else {
+                classDoc.description = normalizeDescription(jsDoc.comment);
+              }
+            }
+
+            /**
+             * Comment-parse doesn't handle annotations with only a description correctly, for example:
+             * @summary foo bar
+             * will output only 'bar' as the description.
+             *
+             * Instead, we use TS for this JSDoc annotation.
+             */
+            jsDoc?.tags?.forEach(tag => {
+              switch(safe(() => tag?.tagName?.getText())) {
+                case 'summary':
+                  classDoc.summary = tag?.comment;
+                  break;
+              }
+            });
+          });
+
+          break;
+      }
+    }
+  }
+}
+
+function handleClassJsDoc(doc, tag) {
+  if(tag?.type) {
+    doc.type = { text: handleJsDocType(tag.type) }
+  }
+
+  if(tag?.description) {
+    doc.description = normalizeDescription(tag.description);
+  }
+
+  if(tag?.name) {
+    doc.name = tag.name === '-' ? '' : tag.name;
+  }
+
+  if(tag?.default) {
+    doc.default = tag.default;
+  }
+
+  return doc;
+}