@dereekb/dbx-cli 13.11.1 → 13.11.3

package/firebase-api-manifest/main.js

@@ -136,7 +136,7 @@ function stripJsonComments(text) {
 import { readdirSync, readFileSync as readFileSync3, statSync } from "node:fs";
 import { join as join2 } from "node:path";
 
-// packages/dbx-cli/firebase-api-manifest/src/generate-api-manifest/extract-crud.ts
+// packages/dbx-cli/manifest-extract/src/lib/extract-crud.ts
 import { Node as Node2, Project as Project2 } from "ts-morph";
 var SUPPORTED_VERBS = /* @__PURE__ */ new Set(["create", "read", "update", "delete", "query"]);
 function extractCrudEntries(source) {
@@ -147,24 +147,51 @@ function extractCrudEntries(source) {
   const crudConfigType = findTypeAliasByEnding(sourceFile, "ModelCrudFunctionsConfig");
   const groupName = inferGroupName(sourceFile);
   const functionsClassName = findFunctionsClassName(sourceFile);
+  const typeDocsCache = /* @__PURE__ */ new Map();
+  const resolveTypeDocs = (typeName) => {
+    if (!typeName) {
+      return void 0;
+    }
+    if (typeDocsCache.has(typeName)) {
+      return typeDocsCache.get(typeName);
+    }
+    const docs = readTypeDocs(sourceFile, typeName);
+    if (docs) {
+      typeDocsCache.set(typeName, docs);
+    }
+    return docs;
+  };
   if (crudConfigType) {
     const literal = crudConfigType.getTypeNode();
     if (literal && Node2.isTypeLiteral(literal)) {
       for (const member of literal.getMembers()) {
-        if (!Node2.isPropertySignature(member)) continue;
+        if (!Node2.isPropertySignature(member)) {
+          continue;
+        }
         const modelName = member.getName();
         modelKeys.push(modelName);
         const valueNode = member.getTypeNode();
-        if (!valueNode) continue;
-        if (isNullLiteralType(valueNode)) continue;
+        if (!valueNode) {
+          continue;
+        }
+        if (isNullLiteralType(valueNode)) {
+          continue;
+        }
         if (Node2.isTypeLiteral(valueNode)) {
           for (const verbMember of valueNode.getMembers()) {
-            if (!Node2.isPropertySignature(verbMember)) continue;
-            const verb = verbMember.getName();
-            if (!SUPPORTED_VERBS.has(verb)) continue;
+            if (!Node2.isPropertySignature(verbMember)) {
+              continue;
+            }
+            const verbName = verbMember.getName();
+            if (!SUPPORTED_VERBS.has(verbName)) {
+              continue;
+            }
+            const verb = verbName;
             const verbValueNode = verbMember.getTypeNode();
-            if (!verbValueNode) continue;
-            collectVerbEntries({ modelName, verb, valueNode: verbValueNode, entries });
+            if (!verbValueNode) {
+              continue;
+            }
+            collectVerbEntries({ modelName, verb, valueNode: verbValueNode, entries, fallbackDescription: readJsDocSummary(verbMember), resolveTypeDocs });
           }
         }
       }
@@ -175,17 +202,26 @@ function extractCrudEntries(source) {
     const literal = functionTypeMap.getTypeNode();
     if (literal && Node2.isTypeLiteral(literal)) {
       for (const member of literal.getMembers()) {
-        if (!Node2.isPropertySignature(member)) continue;
+        if (!Node2.isPropertySignature(member)) {
+          continue;
+        }
         const key = member.getName();
         const valueNode = member.getTypeNode();
         const tuple = valueNode ? readTupleParamsResult(valueNode) : void 0;
+        const paramsDocs = resolveTypeDocs(tuple?.params);
+        const resultDocs = resolveTypeDocs(tuple?.result);
         entries.push({
           model: key,
           verb: "standalone",
           specifier: void 0,
           paramsTypeName: tuple?.params,
           resultTypeName: tuple?.result,
-          line: member.getStartLineNumber()
+          line: member.getStartLineNumber(),
+          description: readJsDocSummary(member),
+          paramsTypeDescription: paramsDocs?.typeDescription,
+          paramsFields: paramsDocs?.fields,
+          resultTypeDescription: resultDocs?.typeDescription,
+          resultFields: resultDocs?.fields
         });
       }
     }
@@ -194,15 +230,21 @@ function extractCrudEntries(source) {
 }
 function findTypeAliasByEnding(sourceFile, ending) {
   for (const alias of sourceFile.getTypeAliases()) {
-    if (alias.getName().endsWith(ending) && alias.getTypeNode()) return alias;
+    if (alias.getName().endsWith(ending) && alias.getTypeNode()) {
+      return alias;
+    }
   }
   return void 0;
 }
 function findFunctionsClassName(sourceFile) {
   for (const cls of sourceFile.getClasses()) {
-    if (!cls.isAbstract()) continue;
+    if (!cls.isAbstract()) {
+      continue;
+    }
     const name = cls.getName();
-    if (name?.endsWith("Functions")) return name;
+    if (name?.endsWith("Functions")) {
+      return name;
+    }
   }
   return void 0;
 }
@@ -211,14 +253,18 @@ function inferGroupName(sourceFile) {
     const name = alias.getName();
     if (name.endsWith("ModelCrudFunctionsConfig")) {
       const stem = name.slice(0, -"ModelCrudFunctionsConfig".length);
-      if (stem.length > 0) return stem;
+      if (stem.length > 0) {
+        return stem;
+      }
     }
   }
   for (const alias of sourceFile.getTypeAliases()) {
     const name = alias.getName();
     if (name.endsWith("FunctionTypeMap")) {
       const stem = name.slice(0, -"FunctionTypeMap".length);
-      if (stem.length > 0) return stem;
+      if (stem.length > 0) {
+        return stem;
+      }
     }
   }
   return void 0;
@@ -226,50 +272,74 @@ function inferGroupName(sourceFile) {
 function isNullLiteralType(node) {
   if (Node2.isLiteralTypeNode(node)) {
     const literal = node.getLiteral();
-    if (Node2.isNullLiteral(literal)) return true;
+    if (Node2.isNullLiteral(literal)) {
+      return true;
+    }
   }
   return false;
 }
 function collectVerbEntries(input) {
-  const { modelName, verb, valueNode, entries } = input;
+  const { modelName, verb, valueNode, entries, fallbackDescription, resolveTypeDocs } = input;
   if (Node2.isTypeLiteral(valueNode)) {
     for (const specMember of valueNode.getMembers()) {
-      if (!Node2.isPropertySignature(specMember)) continue;
+      if (!Node2.isPropertySignature(specMember)) {
+        continue;
+      }
       const specifier = specMember.getName();
       const leafNode = specMember.getTypeNode();
       const leaf2 = leafNode ? readTupleParamsResult(leafNode) ?? readBareParams(leafNode) : void 0;
+      const paramsDocs2 = resolveTypeDocs(leaf2?.params);
+      const resultDocs2 = resolveTypeDocs(leaf2?.result);
       entries.push({
         model: modelName,
         verb,
         specifier,
         paramsTypeName: leaf2?.params,
         resultTypeName: leaf2?.result,
-        line: specMember.getStartLineNumber()
+        line: specMember.getStartLineNumber(),
+        description: readJsDocSummary(specMember),
+        paramsTypeDescription: paramsDocs2?.typeDescription,
+        paramsFields: paramsDocs2?.fields,
+        resultTypeDescription: resultDocs2?.typeDescription,
+        resultFields: resultDocs2?.fields
       });
     }
     return;
   }
   const leaf = readTupleParamsResult(valueNode) ?? readBareParams(valueNode);
+  const paramsDocs = resolveTypeDocs(leaf?.params);
+  const resultDocs = resolveTypeDocs(leaf?.result);
   entries.push({
     model: modelName,
     verb,
     specifier: void 0,
     paramsTypeName: leaf?.params,
     resultTypeName: leaf?.result,
-    line: valueNode.getStartLineNumber()
+    line: valueNode.getStartLineNumber(),
+    description: fallbackDescription,
+    paramsTypeDescription: paramsDocs?.typeDescription,
+    paramsFields: paramsDocs?.fields,
+    resultTypeDescription: resultDocs?.typeDescription,
+    resultFields: resultDocs?.fields
   });
 }
 function readTupleParamsResult(node) {
-  if (!Node2.isTupleTypeNode(node)) return void 0;
+  if (!Node2.isTupleTypeNode(node)) {
+    return void 0;
+  }
   const elements = node.getElements();
-  if (elements.length === 0) return void 0;
+  if (elements.length === 0) {
+    return void 0;
+  }
   const params = elements[0] ? typeNodeName(elements[0]) : void 0;
   const result = elements[1] ? typeNodeName(elements[1]) : void 0;
   return { params, result };
 }
 function readBareParams(node) {
   const params = typeNodeName(node);
-  if (!params) return void 0;
+  if (!params) {
+    return void 0;
+  }
   return { params, result: void 0 };
 }
 function typeNodeName(node) {
@@ -279,6 +349,40 @@ function typeNodeName(node) {
   const text = node.getText().trim();
   return text.length > 0 ? text : void 0;
 }
+function readTypeDocs(sourceFile, typeName) {
+  const interfaceDecl = sourceFile.getInterface(typeName);
+  if (interfaceDecl) {
+    const typeDescription = readJsDocSummary(interfaceDecl);
+    const fields = [];
+    for (const property of interfaceDecl.getProperties()) {
+      const fieldName = property.getName();
+      const description = readJsDocSummary(property);
+      const typeNode = property.getTypeNode();
+      const typeText = typeNode?.getText().trim() ?? "";
+      const field = description ? { name: fieldName, typeText, description } : { name: fieldName, typeText };
+      fields.push(field);
+    }
+    if (!typeDescription && fields.length === 0) {
+      return void 0;
+    }
+    return { typeDescription, fields: fields.length > 0 ? fields : void 0 };
+  }
+  const typeAlias = sourceFile.getTypeAlias(typeName);
+  if (typeAlias) {
+    const typeDescription = readJsDocSummary(typeAlias);
+    return typeDescription ? { typeDescription } : void 0;
+  }
+  return void 0;
+}
+function readJsDocSummary(node) {
+  const docs = node.getJsDocs();
+  if (docs.length === 0) {
+    return void 0;
+  }
+  const last = docs[docs.length - 1];
+  const description = last.getDescription().trim();
+  return description.length > 0 ? description : void 0;
+}
 
 // packages/dbx-cli/firebase-api-manifest/src/generate-api-manifest/find-api-files.ts
 function findApiFiles(packageRoot) {
@@ -437,10 +541,23 @@ function renderEntry({ entry, validatorName }) {
     validatorName ? `paramsValidator: ${validatorName}` : void 0,
     entry.resultTypeName ? `resultTypeName: ${JSON.stringify(entry.resultTypeName)}` : void 0,
     `groupName: ${JSON.stringify(entry.groupName)}`,
-    `sourceFile: ${JSON.stringify(entry.sourceFile)}`
+    `sourceFile: ${JSON.stringify(entry.sourceFile)}`,
+    entry.description ? `description: ${JSON.stringify(entry.description)}` : void 0,
+    entry.paramsTypeDescription ? `paramsTypeDescription: ${JSON.stringify(entry.paramsTypeDescription)}` : void 0,
+    entry.paramsFields && entry.paramsFields.length > 0 ? `paramsFields: ${renderDocFields(entry.paramsFields)}` : void 0,
+    entry.resultTypeDescription ? `resultTypeDescription: ${JSON.stringify(entry.resultTypeDescription)}` : void 0,
+    entry.resultFields && entry.resultFields.length > 0 ? `resultFields: ${renderDocFields(entry.resultFields)}` : void 0
   ];
   return `  { ${fields.filter((v) => Boolean(v)).join(", ")} }`;
 }
+function renderDocFields(fields) {
+  const items = fields.map((field) => {
+    const parts = [`name: ${JSON.stringify(field.name)}`, `typeText: ${JSON.stringify(field.typeText)}`];
+    if (field.description) parts.push(`description: ${JSON.stringify(field.description)}`);
+    return `{ ${parts.join(", ")} }`;
+  });
+  return `[${items.join(", ")}]`;
+}
 async function formatWithPrettier(source, outputFile) {
   const config = await resolveConfig(outputFile);
   return format(source, { ...config, filepath: outputFile });

package/firebase-api-manifest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli-firebase-api-manifest",
-  "version": "13.11.1",
+  "version": "13.11.3",
   "private": true,
   "type": "module",
   "devDependencies": {