fix(-selector-builder): fetch namespace members and comments from docs

Author: nemni8

scripts/selector-declaration-builder.js

@@ -5,9 +5,19 @@ const {
   dtsObjectTypeAlias,
   convertTreeToString
 } = docworksDts.dtsGenerator;
+const { convertOperationToFunction } = docworksDts.docworksToDtsConverters;
 
 const QUERYABLE_TYPE = "TypeNameToSdkType";
 const $W = "$w";
+const $W_MEMBERS_KEY = "/** $W_NAMESPACE_MEMBERS */";
+const DECLARE_KEYWORD = "declare";
+function find$wService(services) {
+  return services.find(
+    service =>
+      service.name === $W &&
+      !Object.prototype.hasOwnProperty.call(service, "memberOf")
+  );
+}
 
 function getQueryableObjectType(services) {
   const isQueryableService = service =>
@@ -20,10 +30,50 @@ function getQueryableObjectType(services) {
   return dtsObjectTypeAlias(QUERYABLE_TYPE, properties);
 }
 
+function extract$wComments(services) {
+  const $wService = find$wService(services);
+  const $wOperation = $wService.operations.find(
+    operation => operation.name === $W
+  );
+  const [$w$wMembersComment] = $wService.operations
+    .filter(o => o.name === $W)
+    .map(operation => operation.docs.summary);
+  return {
+    $W_GLOBAL_DECLARATION_COMMENT: $wOperation.docs.summary,
+    $W_NAMESPACE_COMMENT: $wService.docs.summary,
+    $W_$W_DECLARATION_COMMENT: $w$wMembersComment
+  };
+}
+
+function extract$wMembers(services) {
+  const $wService = find$wService(services);
+  const $wMembersOperations = $wService.operations
+    .filter(o => o.name !== $W)
+    .map(operation => {
+      return convertOperationToFunction($wService, operation, {
+        documentationGenerator: ({ summary }) => summary
+      });
+    });
+
+  return convertTreeToString($wMembersOperations)
+    .split(DECLARE_KEYWORD)
+    .join("")
+    .split("\n")
+    .join("\n\t");
+}
+
 function $wDeclarationBuilder(services) {
+  const $wComments = extract$wComments(services);
+  const $wMembers = extract$wMembers(services);
   const queryableType = getQueryableObjectType(services);
 
-  const page$w = fs.readFileSync("./src_types/pages/$w.d.ts", null, "utf-8");
+  let page$w = fs.readFileSync("./src_types/pages/$w.d.ts", "utf-8");
+  page$w = page$w.replace($W_MEMBERS_KEY, $wMembers);
+  page$w = Object.keys($wComments).reduce(
+    (dts, commnetKey) => dts.replace(commnetKey, $wComments[commnetKey]),
+    page$w
+  );
+
   return [convertTreeToString({ queryableType }), page$w].join("\n");
 }
 

src_types/pages/$w.d.ts

@@ -1,6 +1,6 @@
 // the first part of this file is being generated by => scripts/selector-declaration-builder.js
 // Run `npm run generate-dts` to generate it
-//todo:: try to improve intersectionArray
+
 type IntersectionArrayAndBase<T, P> = {
     [K in keyof T]: K extends P ? T[K] : T[K] & T[K][];
 };
@@ -15,42 +15,33 @@ type VaildSelectorsChars = WixElementSelector | LegalChars
 
 type OnlyVaildSelectorsChars<S> =
     S extends ""
-        ? any
+        ? unknown
         : S extends `${VaildSelectorsChars}${infer Tail}`
             ? OnlyVaildSelectorsChars<Tail>
             : never
 
 type HasComma<S> = 
     S extends `${CommaChar}${infer Tail}`
         ? unknown
-        : S extends `${VaildSelectorsChars}${infer Tail2}`
-            ? HasComma<Tail2>
+        : S extends `${VaildSelectorsChars}${infer Tail}`
+            ? HasComma<Tail>
             : never
+            
 type MultiSelector<S> = S & OnlyVaildSelectorsChars<S> & HasComma<S>
 /**
- * Selects and returns elements from a page.
+ * $W_GLOBAL_DECLARATION_COMMENT
  */
 declare function $w<T extends WixElementSelector, S extends string>(selector: T | MultiSelector<S>):
     S extends keyof WixElements 
         ? WixElements[S]
         : any
 /**
- * The `$w` namespace contains everything you need in order to work
- *  with your site's components.
+ * $W_NAMESPACE_COMMENT
  */
 declare namespace $w {
+    /** $W_NAMESPACE_MEMBERS */
     /**
-     * Gets a selector function for a specific context.
-     */
-    function at(context: $w.Event.EventContext): $w.$w;
-
-    /**
-     * Sets the function that runs when all the page elements have finished loading.
-     */
-    function onReady(initFunction: $w.ReadyHandler): void;
-
-    /**
-     * Selects and returns elements from a page.
+     * $W_$W_DECLARATION_COMMENT
      */
     type $w = <T extends WixElementSelector, S extends string>(selector: T | MultiSelector<S>) =>
         S extends keyof WixElements 

test/it/__snapshots__/negative.spec.js.snap

@@ -4,7 +4,7 @@ exports[`typescript - negative scenarios - configPaths flow should fail compilin
 
 exports[`typescript - negative scenarios - configPaths flow should fail compiling test/it/code-samples/negative/backend-unknown-module folder 1`] = `"unknown.js (2,15): Cannot find module 'custom-modulezzz' or its corresponding type declarations.,unknown.js (3,11): Cannot find name 'wixUnknownModule'."`;
 
-exports[`typescript - negative scenarios - configPaths flow should fail compiling test/it/code-samples/negative/pages-$w-selector folder 1`] = `"index.js (7,18): Property 'zProperty' does not exist on type 'Button'.,index.js (10,6): Argument of type '\\"#appwidget1, AnotherSelector\\"' is not assignable to parameter of type '\\"Document\\" | \\"AccountNavBar\\" | \\"Anchor\\" | \\"Box\\" | \\"Button\\" | \\"Checkbox\\" | \\"CheckboxGroup\\" | \\"Column\\" | \\"ColumnStrip\\" | \\"Container\\" | \\"DatePicker\\" | \\"Dropdown\\" | \\"Footer\\" | \\"Gallery\\" | ... 43 more ... | \\"#wixChat1\\"'.,index.js (13,6): Argument of type 'string' is not assignable to parameter of type '\\"Document\\" | \\"AccountNavBar\\" | \\"Anchor\\" | \\"Box\\" | \\"Button\\" | \\"Checkbox\\" | \\"CheckboxGroup\\" | \\"Column\\" | \\"ColumnStrip\\" | \\"Container\\" | \\"DatePicker\\" | \\"Dropdown\\" | \\"Footer\\" | \\"Gallery\\" | ... 43 more ... | \\"#wixChat1\\"'."`;
+exports[`typescript - negative scenarios - configPaths flow should fail compiling test/it/code-samples/negative/pages-$w-selector folder 1`] = `"index.js (7,18): Property 'zProperty' does not exist on type 'Button'.,index.js (10,6): Argument of type '\\"#appwidget1, AnotherSelector\\"' is not assignable to parameter of type 'WixElementSelector'.,index.js (13,6): Argument of type 'string' is not assignable to parameter of type 'WixElementSelector'."`;
 
 exports[`typescript - negative scenarios - configPaths flow should fail compiling test/it/code-samples/negative/pages-bad-usage-of-existing-prop-on-container-children folder 1`] = `"pageCode.js (2,19): Argument of type 'string' is not assignable to parameter of type 'MouseEventHandler'."`;
 
@@ -28,7 +28,7 @@ exports[`typescript - negative scenarios - declarations flow should fail compili
 
 exports[`typescript - negative scenarios - declarations flow should fail compiling test/it/code-samples/negative/backend-unknown-module folder 1`] = `"unknown.js (2,15): Cannot find module 'custom-modulezzz' or its corresponding type declarations.,unknown.js (3,11): Cannot find name 'wixUnknownModule'."`;
 
-exports[`typescript - negative scenarios - declarations flow should fail compiling test/it/code-samples/negative/pages-$w-selector folder 1`] = `"index.js (7,18): Property 'zProperty' does not exist on type 'Button'.,index.js (10,6): Argument of type '\\"#appwidget1, AnotherSelector\\"' is not assignable to parameter of type '\\"Document\\" | \\"AccountNavBar\\" | \\"Anchor\\" | \\"Box\\" | \\"Button\\" | \\"Checkbox\\" | \\"CheckboxGroup\\" | \\"Column\\" | \\"ColumnStrip\\" | \\"Container\\" | \\"DatePicker\\" | \\"Dropdown\\" | \\"Footer\\" | \\"Gallery\\" | ... 43 more ... | \\"#wixChat1\\"'.,index.js (13,6): Argument of type 'string' is not assignable to parameter of type '\\"Document\\" | \\"AccountNavBar\\" | \\"Anchor\\" | \\"Box\\" | \\"Button\\" | \\"Checkbox\\" | \\"CheckboxGroup\\" | \\"Column\\" | \\"ColumnStrip\\" | \\"Container\\" | \\"DatePicker\\" | \\"Dropdown\\" | \\"Footer\\" | \\"Gallery\\" | ... 43 more ... | \\"#wixChat1\\"'."`;
+exports[`typescript - negative scenarios - declarations flow should fail compiling test/it/code-samples/negative/pages-$w-selector folder 1`] = `"index.js (7,18): Property 'zProperty' does not exist on type 'Button'.,index.js (10,6): Argument of type '\\"#appwidget1, AnotherSelector\\"' is not assignable to parameter of type 'WixElementSelector'.,index.js (13,6): Argument of type 'string' is not assignable to parameter of type 'WixElementSelector'."`;
 
 exports[`typescript - negative scenarios - declarations flow should fail compiling test/it/code-samples/negative/pages-bad-usage-of-existing-prop-on-container-children folder 1`] = `"pageCode.js (2,19): Argument of type 'string' is not assignable to parameter of type 'MouseEventHandler'."`;