@next-core/build-next-bricks 1.5.3 → 1.6.0

package/bin/build-next-bricks.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { existsSync } from "node:fs";
 import build from "../src/build.js";
 import scanBricks from "../src/scanBricks.js";
-import generateMetadata from "../src/generateMetadata.js";
+import generatePkgBuild from "../src/generatePkgBuild.js";
 
 /**
  * @typedef {T | Array<T>} MaybeArray<T>
@@ -68,7 +68,7 @@ try {
     });
 
     if (configList.some((config) => !config.type || config.type === "bricks")) {
-      await generateMetadata(packageDir);
+      await generatePkgBuild(packageDir);
     }
 
     console.log(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next-core/build-next-bricks",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Build next bricks",
   "homepage": "https://github.com/easyops-cn/next-core/tree/v3/packages/build-next-bricks",
   "license": "GPL-3.0",
@@ -38,6 +38,7 @@
     "css-loader": "^6.7.4",
     "cssnano": "^6.0.1",
     "cssnano-preset-lite": "^3.0.0",
+    "doctrine": "^3.0.0",
     "lodash": "^4.17.21",
     "mini-css-extract-plugin": "^2.7.6",
     "postcss": "^8.4.23",
@@ -47,5 +48,8 @@
     "typescript": "^5.0.4",
     "webpack": "^5.84.1"
   },
-  "gitHead": "d8ed3d57b38b9626e70cbb84e61542cc3c269556"
+  "devDependencies": {
+    "@next-core/brick-manifest": "^0.1.0"
+  },
+  "gitHead": "1f4fb165de7f1f1a9dd2de5586748b5d08d21d7c"
 }

package/src/EmitBricksJsonPlugin.js

@@ -1,10 +1,14 @@
 import webpack from "webpack";
 
+/**
+ * @typedef {import("@next-core/brick-manifest").PackageManifest} PackageManifest
+ */
+
 const pluginName = "EmitBricksJsonPlugin";
 
 export default class EmitBricksJsonPlugin {
   /**
-   * @param {{ packageName: string; bricks: string[]; processors: string[]; dependencies: Record<string, string[]>; }} options
+   * @param {{ packageName: string; bricks: string[]; processors: string[]; dependencies: Record<string, string[]>; manifest: PackageManifest; }} options
    */
   constructor(options) {
     this.packageName = options.packageName;
@@ -12,6 +16,7 @@ export default class EmitBricksJsonPlugin {
     this.elements = options.elements;
     this.processors = options.processors;
     this.dependencies = options.dependencies;
+    this.manifest = options.manifest;
   }
 
   /**
@@ -60,6 +65,12 @@ export default class EmitBricksJsonPlugin {
             new webpack.sources.RawSource(bricksJson, false)
           );
 
+          const manifestJson = JSON.stringify(this.manifest, null, 2);
+          compilation.emitAsset(
+            "manifest.json",
+            new webpack.sources.RawSource(manifestJson, false)
+          );
+
           console.log("Defined bricks:", this.bricks);
           console.log("Defined elements:", this.elements);
           console.log("Defined processors:", this.processors);

package/src/build.js

@@ -365,6 +365,7 @@ async function getWebpackConfig(config) {
               elements,
               processors,
               dependencies: config.dependencies,
+              manifest: config.manifest,
             }),
           ]
         : []),

package/src/{generateMetadata.js → generatePkgBuild.js}

@@ -9,7 +9,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /**
  * @param {string} packageDir
  */
-export default async function generateMetadata(packageDir) {
+export default async function generatePkgBuild(packageDir) {
   const targetPkgBuildDir = path.join(packageDir, ".pkgbuild");
   if (!existsSync(targetPkgBuildDir)) {
     mkdirSync(targetPkgBuildDir);

package/src/makeBrickManifest.js

@@ -0,0 +1,299 @@
+import { parse } from "doctrine";
+
+/**
+ * @typedef {import("@next-core/brick-manifest").BrickManifest} BrickManifest
+ * @typedef {import("@next-core/brick-manifest").PropertyManifest} PropertyManifest
+ * @typedef {import("@next-core/brick-manifest").EventManifest} EventManifest
+ * @typedef {import("@next-core/brick-manifest").MethodManifest} MethodManifest
+ * @typedef {import("@babel/types").Node} Node
+ * @typedef {import("@babel/traverse").NodePath} NodePath
+ * @typedef {import("@babel/types").ClassDeclaration} ClassDeclaration
+ * @typedef {import("doctrine").Tag} Tag
+ */
+
+/**
+ * @param {string} name
+ * @param {NodePath} nodePath
+ * @param {string} source
+ * @returns {BrickManifest}
+ */
+export default function makeBrickManifest(name, nodePath, source) {
+  /** @type {import("@babel/traverse").NodePath<ClassDeclaration>} */
+  const classPath = nodePath.parentPath;
+  /** @type {BrickManifest} */
+  const manifest = {
+    name,
+    properties: [],
+    events: [],
+    slots: [],
+    methods: [],
+  };
+
+  const docComment = findDocComment(nodePath, source);
+  if (docComment) {
+    manifest.description = docComment.description;
+    for (const tag of docComment.tags) {
+      if (tag.title === "slot") {
+        const match = tag.description.match(/^(?:([-\w]+)\s+-\s+)?(.*)$/);
+        if (!match) {
+          throw new Error(
+            `Doc comment for slot is invalid: '${tag.description}'`
+          );
+        }
+        manifest.slots.push({
+          name: match[1] ?? null,
+          description: match[2],
+        });
+      }
+    }
+  }
+
+  scanFields(manifest, classPath.node.body.body, source);
+
+  return manifest;
+}
+
+/**
+ * @param {NodePath} nodePath
+ * @param {string} source
+ */
+function findDocComment({ node, parentPath }, source) {
+  if (node.type !== "Program") {
+    const docComment = parseDocComment(node, source);
+    if (docComment) {
+      return docComment;
+    }
+  }
+  if (parentPath) {
+    return findDocComment(parentPath, source);
+  }
+}
+
+/**
+ * @param {BrickManifest} manifest
+ * @param {Node[]} nodes
+ * @param {string} source
+ */
+function scanFields(manifest, nodes, source) {
+  for (const node of nodes) {
+    if (node.type === "ClassAccessorProperty" && node.decorators?.length) {
+      for (const { expression } of node.decorators) {
+        if (
+          expression.type === "CallExpression" &&
+          expression.callee.type === "Identifier"
+        ) {
+          switch (expression.callee.name) {
+            case "property": {
+              /** @type {PropertyManifest} */
+              const prop = {
+                name: node.key.name,
+              };
+              const docComment = parseDocComment(node, source);
+              if (docComment) {
+                prop.description = docComment.description;
+                prop.required = getBooleanTag(docComment.tags, "required");
+                prop.deprecated = getDeprecatedInfo(docComment.tags);
+                prop.default = findTag(docComment.tags, "default")?.description;
+              }
+              // Find out the `attribute` option for the property.
+              if (expression.arguments.length > 0) {
+                const options = expression.arguments[0];
+                if (options.type === "ObjectExpression") {
+                  for (const opt of options.properties) {
+                    if (
+                      opt.type === "ObjectProperty" &&
+                      !opt.computed &&
+                      opt.key.type === "Identifier" &&
+                      opt.key.name === "attribute"
+                    ) {
+                      if (
+                        opt.value.type === "BooleanLiteral" ||
+                        opt.value.type === "StringLiteral"
+                      ) {
+                        prop.attribute = opt.value.value;
+                      }
+                      break;
+                    }
+                  }
+                }
+              }
+              // Find out the type annotation for the property.
+              if (
+                node.typeAnnotation &&
+                node.typeAnnotation.type === "TSTypeAnnotation"
+              ) {
+                const { typeAnnotation } = node.typeAnnotation;
+                prop.type = getTypeWithoutUndefined(typeAnnotation, source);
+              }
+              if (node.value && !prop.default) {
+                prop.default = source.substring(
+                  node.value.start,
+                  node.value.end
+                );
+              }
+              manifest.properties.push(prop);
+              break;
+            }
+
+            case "event": {
+              /** @type {EventManifest} */
+              const event = {};
+
+              // Find out the `type` option for the event.
+              if (expression.arguments.length > 0) {
+                const options = expression.arguments[0];
+                if (options.type === "ObjectExpression") {
+                  for (const opt of options.properties) {
+                    if (
+                      opt.type === "ObjectProperty" &&
+                      !opt.computed &&
+                      opt.key.type === "Identifier" &&
+                      opt.key.name === "type"
+                    ) {
+                      if (opt.value.type === "StringLiteral") {
+                        event.name = opt.value.value;
+                      }
+                      break;
+                    }
+                  }
+                }
+              }
+              if (event.name === undefined) {
+                throw new Error(
+                  `Invalid @event() call: no literal type option in event '${node.key.name}'`
+                );
+              }
+              const docComment = parseDocComment(node, source);
+              if (docComment) {
+                event.description = docComment.description;
+                event.deprecated = getDeprecatedInfo(docComment.tags);
+                const detailTag = findTag(docComment.tags, "detail");
+                if (detailTag) {
+                  event.detail ??= {};
+                  event.detail.description = detailTag.description;
+                }
+              }
+              // Find out the type annotation for the event detail.
+              if (
+                node.typeAnnotation &&
+                node.typeAnnotation.type === "TSTypeAnnotation"
+              ) {
+                const { typeAnnotation } = node.typeAnnotation;
+                if (
+                  typeAnnotation.type === "TSTypeReference" &&
+                  typeAnnotation.typeName.type === "Identifier" &&
+                  typeAnnotation.typeName.name === "EventEmitter"
+                ) {
+                  // Extract the parameters from `EventEmitter`
+                  const param = typeAnnotation.typeParameters.params[0];
+                  event.detail ??= {};
+                  event.detail.type = source.substring(param.start, param.end);
+                }
+              }
+              manifest.events.push(event);
+              break;
+            }
+          }
+        }
+      }
+    } else if (node.type === "ClassMethod" && node.decorators?.length) {
+      for (const { expression } of node.decorators) {
+        if (
+          expression.type === "CallExpression" &&
+          expression.callee.type === "Identifier" &&
+          expression.callee.name === "method"
+        ) {
+          /** @type {MethodManifest} */
+          const method = {
+            name: node.key.name,
+            params: [],
+          };
+          const docComment = parseDocComment(node, source);
+          if (docComment) {
+            method.description = docComment.description;
+            method.deprecated = getDeprecatedInfo(docComment.tags);
+          }
+          for (const param of node.params) {
+            method.params.push(source.substring(param.start, param.end));
+          }
+          if (node.returnType && node.returnType.type === "TSTypeAnnotation") {
+            const { typeAnnotation } = node.returnType;
+            method.return ??= {};
+            method.return.type = source.substring(
+              typeAnnotation.start,
+              typeAnnotation.end
+            );
+          }
+          manifest.methods.push(method);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * @param {Node[]} nodes
+ * @param {string} source
+ */
+function parseDocComment(node, source) {
+  if (node.leadingComments) {
+    const docComment = node.leadingComments.find(
+      (comment) => comment.type === "CommentBlock"
+    );
+    if (docComment) {
+      const docSource = source.substring(docComment.start, docComment.end);
+      const parsed = parse(docSource, { unwrap: true });
+      return parsed;
+    }
+  }
+}
+
+/**
+ * @param {Node} node
+ * @param {string} source
+ */
+function getTypeWithoutUndefined(node, source) {
+  if (node.type === "TSUnionType") {
+    const filteredTypes = node.types.filter(
+      (type) => type.type !== "TSUndefinedKeyword"
+    );
+    if (filteredTypes.length < node.types.length) {
+      return filteredTypes
+        .map((type) => source.substring(type.start, type.end))
+        .join(" | ");
+    }
+  }
+  return source.substring(node.start, node.end);
+}
+
+/**
+ * @param {Tag[]} tags
+ * @param {string} title
+ * @returns {Tag | undefined}
+ */
+function findTag(tags, title) {
+  for (const tag of tags) {
+    if (tag.title === title) {
+      return tag;
+    }
+  }
+}
+
+/**
+ * @param {Tag[]} tags
+ * @param {string} title
+ * @returns {boolean | undefined}
+ */
+function getBooleanTag(tags, title) {
+  const tag = findTag(tags, title);
+  return tag ? true : undefined;
+}
+
+/**
+ * @param {Tag[]} tags
+ * @returns {boolean | string | undefined}
+ */
+function getDeprecatedInfo(tags) {
+  const tag = findTag(tags, "deprecated");
+  return tag ? (tag.description === null ? true : tag.description) : undefined;
+}

package/src/scanBricks.js

@@ -1,10 +1,17 @@
 import path from "node:path";
 import fs, { existsSync, statSync } from "node:fs";
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { parse } from "@babel/parser";
 import babelTraverse from "@babel/traverse";
 import _ from "lodash";
 import getCamelPackageName from "./getCamelPackageName.js";
+import makeBrickManifest from "./makeBrickManifest.js";
+
+/**
+ * @typedef {import("@next-core/brick-manifest").PackageManifest} PackageManifest
+ * @typedef {{import: string; name: string; noNamespace?: boolean;}} Expose
+ * @typedef {Record<string, Expose>} Exposes
+ */
 
 const { default: traverse } = babelTraverse;
 const { escapeRegExp } = _;
@@ -19,10 +26,10 @@ const validExposeName = /^[-\w]+$/;
  * Scan defined bricks by AST.
  *
  * @param {string} packageDir
- * @returns {Promise<{exposes: Record<string, { import: string; name: string; noNamespace?: boolean; }; dependencies: Record<string, string[]>}>>}
+ * @returns {Promise<{exposes: Exposes; dependencies: Record<string, string[]>; manifest: PackageManifest}>}
  */
 export default async function scanBricks(packageDir) {
-  /** @type {Map<string, { import: string; name: string; }>} */
+  /** @type {Map<string, Expose>} */
   const exposes = new Map();
   /** @type {Record<string, string[]>} */
   const specifiedDeps = {};
@@ -38,6 +45,14 @@ export default async function scanBricks(packageDir) {
   const packageName = packageJson.name.split("/").pop();
   const camelPackageName = getCamelPackageName(packageName);
 
+  /** @type {PackageManifest} */
+  const manifest = {
+    manifest_version: 1,
+    package: packageJson.name,
+    name: packageName,
+    bricks: [],
+  };
+
   /** @type {Map<string, Set<string>} */
   const usingWrappedBricks = new Map();
 
@@ -302,7 +317,10 @@ export default async function scanBricks(packageDir) {
           }
         }
       },
-      Decorator({ node: { expression } }) {
+      Decorator(nodePath) {
+        const {
+          node: { expression },
+        } = nodePath;
         // Match `@defineElement(...)`
         if (
           expression.type === "CallExpression" &&
@@ -372,6 +390,8 @@ export default async function scanBricks(packageDir) {
 
           brickSourceFiles.set(fullName, filePath);
 
+          manifest.bricks.push(makeBrickManifest(fullName, nodePath, content));
+
           exposes.set(`./${brickName}`, {
             import: `./${path
               .relative(packageDir, overrideImport || filePath)
@@ -503,5 +523,6 @@ export default async function scanBricks(packageDir) {
       ...analyzedDeps,
       ...specifiedDeps,
     },
+    manifest,
   };
 }