[DXEC-763] Fix/comment parsing (#315)

* fix: comment parsing return value

* fix: move description to the top of the comment

build

@@ -37,19 +37,23 @@ async.reduce(files, [], (rules, file, callback) => {
     // strip the opening comment and remove extra newlines
     const code = data.split('\n').slice(parsed.loc.end.line).join('\n').trim();
 
-    if (argv.allRules || parsed.gallery === 'true') {
-      const ruleDescription = converter.makeHtml(parsed.example);
+    const ruleTags = {};
+    parsed.tags.forEach((tag) => ruleTags[tag.title] = tag.description);
+
+    if (argv.allRules || ruleTags.gallery === 'true') {
+      const ruleExample = parsed.examples.reduce((prev, curr) => "\n\n" + curr.description + "\n<pre><code>" + curr.value + "</code></pre>" + prev, "");
+      const ruleDescription = converter.makeHtml(parsed.description + ruleExample);
 
       if (!ruleDescription) {
-        return callback(new Error(`Blank description for ${parsed.title}`));
+        return callback(new Error(`Blank description for ${file}`));
       }
 
       const rule = {
         id: path.basename(file).replace('.js', ''),
-        title: parsed.title,
-        overview: parsed.overview,
-        categories: parsed.category ? parsed.category.split(',') : ['default'],
-        description: converter.makeHtml(parsed.example),
+        title: ruleTags.title,
+        overview: ruleTags.overview,
+        categories: ruleTags.category ? ruleTags.category.split(',') : ['default'],
+        description: ruleDescription,
         code
       };
       rules.push(rule);

src/rules/access-on-weekdays-only-for-an-app.js

@@ -1,11 +1,10 @@
 /**
+ * This rule is used to prevent access during weekends for a specific app.
+ * 
  * @title Allow Access during weekdays for a specific App
  * @overview Prevent access to app during weekends.
  * @gallery true
  * @category access control
- *
- * This rule is used to prevent access during weekends for a specific app.
- *
  */
 
 function accessOnWeekdaysOnly(user, context, callback) {

src/rules/active-directory-groups.js

@@ -1,13 +1,12 @@
 /**
+ * This rule checks if a user belongs to an AD group and if not, it will return Access Denied.
+ *
+ * > Note: you can mix this with `context.clientID` or `clientName` to do it only for specific application
+ * 
  * @title Active Directory group membership
  * @overview Check Active Directory membership, else return Access Denied.
  * @gallery true
  * @category access control
- *
- * This rule checks if a user belongs to an AD group and if not, it will return Access Denied.
- *
- * > Note: you can mix this with `context.clientID` or `clientName` to do it only for specific application
- *
  */
 
 function activeDirectoryGroups(user, context, callback) {

src/rules/adaptive-mfa.js

@@ -1,15 +1,15 @@
 /**
- * @title Adaptive MFA
- * @overview Trigger multifactor authentication for a specific risk assessment result.
- * @gallery true
- * @category multifactor
  *
  * This rule is used to trigger multifactor authentication when a specific risk assessment result is detected.
  *
  * The `context.riskAssessment` attribute will be available only when Adaptive MFA is enabled for your tenant. Use of the Adaptive MFA feature requires an add-on for the Enterprise plan. Please contact sales with any questions.
  *
  * For more information about Adaptive MFA and the `context.riskAssessment` attribute, read our [full documentation](https://auth0.com/docs/mfa/adaptive-mfa).
  *
+ * @title Adaptive MFA
+ * @overview Trigger multifactor authentication for a specific risk assessment result.
+ * @gallery true
+ * @category multifactor
  */
 
 function adaptiveMfa(user, context, callback) {

src/rules/add-attributes.js

@@ -1,13 +1,13 @@
 /**
- * @title Add attributes to a user for specific connection
- * @overview Add attributes to a user for specific connection.
- * @gallery true
- * @category enrich profile
  *
  * This rule will add an attribute to the user only for the login transaction (i.e. they won't be persisted to the user).
  *
  * This is useful for cases where you want to enrich the user information for a specific application.
  *
+ * @title Add attributes to a user for specific connection
+ * @overview Add attributes to a user for specific connection.
+ * @gallery true
+ * @category enrich profile
  */
 
 function addAttributes(user, context, callback) {

src/rules/add-country.js

@@ -1,8 +1,4 @@
 /**
- * @title Add country to the user profile
- * @overview Add a country attribute to the user based on their IP address.
- * @gallery true
- * @category enrich profile
  *
  * This rule will add a `country` attribute to the user based on their ip address.
  *
@@ -22,6 +18,10 @@
  * }
  * ```
  *
+ * @title Add country to the user profile
+ * @overview Add a country attribute to the user based on their IP address.
+ * @gallery true
+ * @category enrich profile
  */
 
 function addCountry(user, context, callback) {

src/rules/add-email-to-access-token.js

@@ -1,12 +1,11 @@
 /**
+ *
+ * This rule will add the authenticated user's `email` attribute value to the access token.
+ *
  * @title Add email to access token
  * @overview Add the authenticated user's email address to the access token.
  * @gallery true
  * @category access control
- *
- * This rule will add the authenticated user's `email` attribute value to the access token.
- *
- *
  */
 
 function addEmailToAccessToken(user, context, callback) {

src/rules/add-persistence-attribute.js

@@ -1,11 +1,11 @@
 /**
+ *
+ * This rule count set the default color (an example preference) to a user (using `user_metadata`).
+ *
  * @title Add persistent attributes to the user
  * @overview Set the default color of a user's `user_metadata`.
  * @gallery true
  * @category enrich profile
- *
- * This rule count set the default color (an example preference) to a user (using `user_metadata`).
- *
  */
 
 function addPersistenceAttribute(user, context, callback) {

src/rules/add-roles-from-sqlserver.js

@@ -1,13 +1,13 @@
 /**
- * @title Add user roles from a SQL Server database
- * @overview Query a SQL server database on each login and add a roles array to the user.
- * @gallery true
- * @category enrich profile
  *
  * This rule will query a SQL server database on each login and add a `roles` array to the user.
  *
  * > Note: you can store the connection string securely on Auth0 encrypted configuration. Also make sure when you call an external endpoint to open your firewall/ports to our IP address which you can find it in the rules editor. This happens when you query SQL Azure for example.
  *
+ * @title Add user roles from a SQL Server database
+ * @overview Query a SQL server database on each login and add a roles array to the user.
+ * @gallery true
+ * @category enrich profile
  */
 
 function addRolesFromSqlServer(user, context, callback) {

src/rules/alt-risk-score.js

@@ -1,14 +1,13 @@
-/* global configuration */
 /**
- * @title Alternate Risk Score
- * @overview Send the user's IP address, user agent, email address and username to MaxMind's MinFraud API.
- * @gallery true
- * @category enrich profile
  *
  * This rule will send the user's IP address, user agent, email address (in MD5) and username (in MD5) to MaxMind's MinFraud API. This API will return information about this current transaction like the location, a risk score, ...
  *
  * > Note: You will need to sign up here to get a license key https://www.maxmind.com/
  *
+ * @title Alternate Risk Score
+ * @overview Send the user's IP address, user agent, email address and username to MaxMind's MinFraud API.
+ * @gallery true
+ * @category enrich profile
  */
 
 // eslint-disable-next-line no-unused-vars

src/rules/appery.js

@@ -1,6 +1,4 @@
 /**
- * @title Generate an Appery.io Session Token
- * @overview Generate a session token for accessing Appery.io Database Services.
  *
  * This rule is used to generate a session token for accessing [Appery.io Database Services](http://appery.io/). The rule adds a new `user.apperyio_session_token` property set to the user profile containing the Appery.io session token. You can use this `session token` to make further Appery.io API calls.
  *
@@ -10,6 +8,8 @@
  *
  * If the user doesn't exist, this rule will auto-provision one, with `email`, `name` or `user_id` as the handle.
  *
+ * @title Generate an Appery.io Session Token
+ * @overview Generate a session token for accessing Appery.io Database Services.
  */
 
 function generateApperySessionToken(user, context, callback) {

src/rules/arengu-policy-acceptance.js

@@ -1,8 +1,4 @@
 /**
- * @title Arengu Policy Acceptance
- * @overview Require your users to accept custom privacy policies or new terms.
- * @gallery false
- * @category marketplace
  *
  * Please see the [Aregnu Policy Acceptance integration](https://marketplace.auth0.com/integrations/arengu-policy-acceptance) for more information and detailed installation instructions.
  *
@@ -11,6 +7,10 @@
  *    - `SESSION_TOKEN_SECRET`: A long, random string at least 32 bytes long
  *    - `ARENGU_POLICIES_FORM_URL`: The URL that contains an [embedded form](https://github.com/arengu/forms-js-sdk#embed-a-form) or with a [hosted form page](https://www.arengu.com/pages)
  *
+ * @title Arengu Policy Acceptance
+ * @overview Require your users to accept custom privacy policies or new terms.
+ * @gallery false
+ * @category marketplace
  */
 
 async function arenguCheckUserPolicies(user, context, callback) {

src/rules/arengu-progressive-profiling.js

@@ -1,8 +1,4 @@
 /**
- * @title Arengu Progressive Profiling
- * @overview Capture new users' information in your authentication flows.
- * @gallery false
- * @category marketplace
  *
  * Please see the [Aregnu Progressive Profiling integration](https://marketplace.auth0.com/integrations/arengu-progressive-profiling) for more information and detailed installation instructions.
  *
@@ -11,6 +7,10 @@
  *    - `SESSION_TOKEN_SECRET`: A long, random string at least 32 bytes long
  *    - `ARENGU_PROFILE_FORM_URL`: The URL that contains an [embedded form](https://github.com/arengu/forms-js-sdk#embed-a-form) or with a [hosted form page](https://www.arengu.com/pages)
  *
+ * @title Arengu Progressive Profiling
+ * @overview Capture new users' information in your authentication flows.
+ * @gallery false
+ * @category marketplace
  */
 
 async function arenguCompleteUserProfile(user, context, callback) {

src/rules/aspnet-webapi.js

@@ -1,8 +1,4 @@
 /**
- * @title Custom webhook with ASPNET WebApi2
- * @overview Post variables sent to your Rule as a custom webhook in an ASP.NET WebApi application.
- * @gallery true
- * @category webhook
  *
  * This rule shows how to post the variables sent to your Rule a custom webhook in an ASP.NET WebApi application. This is useful for situations where you want to enrich the User's profile with your internal ID before the JsonWebToken is created, or if you want to seamlessly register new users.
  *
@@ -16,6 +12,10 @@
  *
  * Contributed by Robert McLaws, AdvancedREI.com
  *
+ * @title Custom webhook with ASPNET WebApi2
+ * @overview Post variables sent to your Rule as a custom webhook in an ASP.NET WebApi application.
+ * @gallery true
+ * @category webhook
  */
 
 function aspnetWebApi(user, context, callback) {

src/rules/caisson-id-check.js

@@ -1,9 +1,4 @@
 /**
- * @title Caisson ID Check
- * @overview Validate US driver's licenses and international passports in real time.
- * @gallery false
- * @category marketplace
- *
  * Please see the [Caisson integration](https://marketplace.auth0.com/integrations/caisson-id-check) for more information and detailed installation instructions.
  *
  * **Required configuration** (this Rule will be skipped if any of the below are not defined):
@@ -15,6 +10,11 @@
  * **Optional configuration:**
  *
  *    - `CAISSON_DEBUG` Set to "true" to log errors in the console
+ * 
+ * @title Caisson ID Check
+ * @overview Validate US driver's licenses and international passports in real time.
+ * @gallery false
+ * @category marketplace
  */
 
 async function caissonIDCheck(user, context, callback) {

src/rules/check-domains-against-connection-aliases.js

@@ -1,14 +1,15 @@
 /**
- * @title Check if user email domain matches configured domain
- * @overview Check user email domain matches domains configured in connection.
- * @gallery true
- * @category access control
  *
  * This rule checks if the user's login email matches any domains configured in an enterprise connection. If there are no matches, the login is denied. But, if there are no domains configured it will allow access.
  *
  * Use this rule to only allow users from specific email domains to login.
  *
  * For example, ExampleCo has setup exampleco.com as a managed domain. They add exampleco.com to the email domains list in their SAML connection. Now, only users with an email ending with @exampleco.com (and not @examplecocorp.com) can login via SAML.
+ * 
+ * @title Check if user email domain matches configured domain
+ * @overview Check user email domain matches domains configured in connection.
+ * @gallery true
+ * @category access control
  */
 
 function checkDomainsAgainstConnectionAliases(user, context, callback) {

src/rules/check-last-password-reset.js

@@ -1,11 +1,11 @@
 /**
+ *
+ * This rule will check the last time that a user changed his or her account password.
+ *
  * @title Check last password reset
  * @overview Check the last time that a user changed his or her account password.
  * @gallery true
  * @category access control
- *
- * This rule will check the last time that a user changed his or her account password.
- *
  */
 
 function checkLastPasswordReset(user, context, callback) {

src/rules/create-new-contact-add-to-contact-list-hubspot.js

@@ -1,8 +1,4 @@
 /**
- * @title Add New Contact to HubSpot for Marketing
- * @overview Add New Contact to HubSpot then add to a List for marketing
- * @gallery true
- * @category webhook
  *
  * This rule will add a New Contact to HubSpot if they don't already exist, and then add that Contact to a List for marketing.
  *
@@ -11,6 +7,11 @@
  * For more details about the Rules configuration settings, see here https://auth0.com/docs/rules/guides/configuration
  * For more information about Hubspot API keys see here https://knowledge.hubspot.com/integrations/how-do-i-get-my-hubspot-api-key
  * Use 1 as the value for HUBSPOT_NEW_MEMBER_LIST_ID for the default list in Hubspot. Otherwise, you can see the ID of any list in HubSpot visiting it, and looking at the URL. It will have this format https://app.hubspot.com/contacts/:portalId/lists/:listId where :listId is the value you want.
+ * 
+ * @title Add New Contact to HubSpot for Marketing
+ * @overview Add New Contact to HubSpot then add to a List for marketing
+ * @gallery true
+ * @category webhook
  */
 
 function createNewContactAndAddToContactListHubSpot(user, context, callback) {

src/rules/creates-lead-salesforce.js

@@ -1,15 +1,15 @@
 /**
- * @title Creates a new Lead in Salesforce on First Login
- * @overview On first login call the Salesforce API to record the contact as a new Lead.
- * @gallery true
- * @category webhook
  *
  * This rule will check if this is the first user login, and in that case will call Salesforce API to record the contact as a new Lead. It is using Salesforce REST APIs and the `resource owner` flow to obtain an `access_token`.
  *
  * The username you use to authenticate the API will appear as the __creator__ of the lead.
  *
  * > Note: this sample implements very basic error handling.
  *
+ * @title Creates a new Lead in Salesforce on First Login
+ * @overview On first login call the Salesforce API to record the contact as a new Lead.
+ * @gallery true
+ * @category webhook
  */
 
 function createLeadSalesforce(user, context, callback) {

src/rules/cumulio-add-metadata-to-tokens.js

@@ -1,12 +1,13 @@
 /**
- * @title User app_metadata for Cumul.io
- * @overview Add Cumul.io user app_metadata to tokens to be used for Cumul.io dashboard filtering
- * @gallery false
- * @category marketplace
  *
  * This integration simplifies the process of making full use of integrated Cumul.io dashboards' multi tenant features
  * by using Auth0 as its authentication layer. The integration will allow you to set up and use user
  * information in Auth0 as Cumul.io parameters to filter and structure your Cumul.io dashboards.
+ * 
+ * @title User app_metadata for Cumul.io
+ * @overview Add Cumul.io user app_metadata to tokens to be used for Cumul.io dashboard filtering
+ * @gallery false
+ * @category marketplace
  */
 
 function addMetadataToTokens(user, context, callback) {

src/rules/default-picture-null-avatars.js

@@ -1,11 +1,11 @@
 /**
+ *
+ * This rule will set a default picture for null avatars via a rule for email-based logins:
+ *
  * @title Default picture for null avatars
  * @overview Set a default picture for null avatars.
  * @gallery true
  * @category enrich profile
- *
- * This rule will set a default picture for null avatars via a rule for email-based logins:
- *
  */
 
 function defaultPictureForNullAvatars(user, context, callback) {