fix(config): add descriptions to JSON schema properties

manifest.json

@@ -8,9 +8,13 @@
     "properties": {
       "evmNetworkId": {
         "default": 100,
+        "description": "Network ID to run in, default to 100",
+        "examples": ["100"],
         "type": "number"
       },
       "evmPrivateEncrypted": {
+        "description": "The encrypted key to use for permit generation",
+        "examples": ["0x000..."],
         "type": "string"
       },
       "erc20RewardToken": {
@@ -22,10 +26,13 @@
         "type": "object",
         "properties": {
           "file": {
+            "description": "Specify a file to write the results in",
+            "examples": ["./result.json"],
             "type": "string"
           },
           "requirePriceLabel": {
             "default": true,
+            "description": "If set to false, the plugin runs even if the price label is missing, and will evaluate comments.",
             "type": "boolean"
           },
           "limitRewards": {
@@ -45,11 +52,15 @@
                     "properties": {
                       "model": {
                         "default": "gpt-4o-2024-08-06",
+                        "description": "OpenAI model, e.g. gpt-4o",
+                        "examples": ["gpt-4o"],
                         "type": "string"
                       },
                       "endpoint": {
                         "default": "https://api.openai.com/v1",
                         "pattern": "^(https?:\\/\\/[^\\s$.?#].\\S*)$",
+                        "description": "OpenAI endpoint for requests",
+                        "examples": ["https://api.openai.com/v1"],
                         "type": "string"
                       }
                     }
@@ -61,11 +72,14 @@
                         "relevance": 1
                       }
                     ],
+                    "description": "Multipliers applied to different types of comments",
                     "type": "array",
                     "items": {
                       "type": "object",
                       "properties": {
                         "role": {
+                          "description": "Roles that this multiplier applies to",
+                          "examples": ["[\"PULL_ASSIGNEE\", \"PULL_AUTHOR\", \"PULL_COLLABORATOR\"]"],
                           "type": "array",
                           "items": {
                             "anyOf": [
@@ -233,6 +247,8 @@
                           }
                         },
                         "relevance": {
+                          "description": "Relevance multiplier for this role",
+                          "examples": ["2"],
                           "type": "number"
                         }
                       },
@@ -254,6 +270,7 @@
                 "properties": {
                   "redeemTask": {
                     "default": true,
+                    "description": "Is the task redeemable, e.g. can the user collect the bounty?",
                     "type": "boolean"
                   }
                 }
@@ -303,6 +320,7 @@
                 "type": "object",
                 "properties": {
                   "multipliers": {
+                    "description": "Multipliers applied to different parts of the comment according the role of the author",
                     "default": [
                       {
                         "role": ["ISSUE_SPECIFICATION"],
@@ -1201,6 +1219,8 @@
                       "properties": {
                         "role": {
                           "minItems": 1,
+                          "description": "The list of roles this multiplier applies to",
+                          "examples": ["[\"PULL_ASSIGNEE\", \"PULL_AUTHOR\", \"PULL_COLLABORATOR\"]"],
                           "type": "array",
                           "items": {
                             "anyOf": [
@@ -1368,13 +1388,16 @@
                           }
                         },
                         "multiplier": {
+                          "examples": ["1"],
+                          "description": "Multiplier for the given list of roles",
                           "type": "number"
                         },
                         "rewards": {
                           "default": {},
                           "type": "object",
                           "properties": {
                             "html": {
+                              "description": "Attributed score per HTML entity",
                               "default": {
                                 "br": {
                                   "score": 0,
@@ -1463,10 +1486,13 @@
                                   "type": "object",
                                   "properties": {
                                     "score": {
+                                      "description": "Score per word in the entity",
+                                      "examples": ["0.1"],
                                       "type": "number"
                                     },
                                     "countWords": {
                                       "default": true,
+                                      "description": "Whether to count words in the entity",
                                       "type": "boolean"
                                     }
                                   },
@@ -1476,6 +1502,7 @@
                             },
                             "wordValue": {
                               "default": 0.1,
+                              "description": "Value multiplier for each word",
                               "type": "number"
                             }
                           }
@@ -1486,6 +1513,8 @@
                   },
                   "wordCountExponent": {
                     "default": 0.85,
+                    "description": "Exponent applied to the word count total",
+                    "examples": ["0.85"],
                     "type": "number"
                   }
                 }
@@ -1516,10 +1545,12 @@
                 "properties": {
                   "post": {
                     "default": true,
+                    "description": "Enables posting to the related GitHub Issue",
                     "type": "boolean"
                   },
                   "debug": {
                     "default": false,
+                    "description": "Enables debug by creating a local html file of the rendered comment",
                     "type": "boolean"
                   }
                 }
@@ -1538,11 +1569,15 @@
           "maxAttempts": {
             "default": 10,
             "minimum": 1,
+            "description": "The maximum amount of retries on failure",
+            "examples": ["10"],
             "type": "number"
           },
           "delayMs": {
             "default": 1000,
             "minimum": 100,
+            "description": "The delay between each retry, in milliseconds",
+            "examples": ["1000"],
             "type": "number"
           }
         }

src/configuration/content-evaluator-config.ts

@@ -6,11 +6,20 @@ const openAiType = Type.Object(
     /**
      * AI model to use for comment evaluation.
      */
-    model: Type.String({ default: "gpt-4o-2024-08-06" }),
+    model: Type.String({
+      default: "gpt-4o-2024-08-06",
+      description: "OpenAI model, e.g. gpt-4o",
+      examples: ["gpt-4o"],
+    }),
     /**
      * Specific endpoint to send the comments to.
      */
-    endpoint: Type.String({ default: "https://api.openai.com/v1", pattern: /^(https?:\/\/[^\s$.?#].\S*)$/i.source }),
+    endpoint: Type.String({
+      default: "https://api.openai.com/v1",
+      pattern: /^(https?:\/\/[^\s$.?#].\S*)$/i.source,
+      description: "OpenAI endpoint for requests",
+      examples: ["https://api.openai.com/v1"],
+    }),
   },
   { default: {} }
 );
@@ -22,8 +31,11 @@ export const contentEvaluatorConfigurationType = Type.Object({
    */
   multipliers: Type.Array(
     Type.Object({
-      role: Type.Array(commentType),
-      relevance: Type.Optional(Type.Number()),
+      role: Type.Array(commentType, {
+        description: "Roles that this multiplier applies to",
+        examples: ['["PULL_ASSIGNEE", "PULL_AUTHOR", "PULL_COLLABORATOR"]'],
+      }),
+      relevance: Type.Optional(Type.Number({ description: "Relevance multiplier for this role", examples: ["2"] })),
     }),
     {
       default: [
@@ -32,6 +44,7 @@ export const contentEvaluatorConfigurationType = Type.Object({
           relevance: 1,
         },
       ],
+      description: "Multipliers applied to different types of comments",
     }
   ),
 });

src/configuration/data-collection-config.ts

@@ -5,11 +5,21 @@ export const dataCollectionConfigurationType = Type.Object(
     /**
      * The maximum amount of retries on failure.
      */
-    maxAttempts: Type.Number({ default: 10, minimum: 1 }),
+    maxAttempts: Type.Number({
+      default: 10,
+      minimum: 1,
+      description: "The maximum amount of retries on failure",
+      examples: ["10"],
+    }),
     /**
      * The delay between each retry, in milliseconds.
      */
-    delayMs: Type.Number({ default: 1000, minimum: 100 }),
+    delayMs: Type.Number({
+      default: 1000,
+      minimum: 100,
+      description: "The delay between each retry, in milliseconds",
+      examples: ["1000"],
+    }),
   },
   { default: {} }
 );

src/configuration/formatting-evaluator-config.ts

@@ -18,14 +18,15 @@ export const wordRegex = /\b\w+\b/;
 export const urlRegex = /https?:\/\/\S+/g;
 
 const htmlEntity = Type.Object({
-  score: Type.Number(),
-  countWords: Type.Boolean({ default: true }),
+  score: Type.Number({ description: "Score per word in the entity", examples: ["0.1"] }),
+  countWords: Type.Boolean({ default: true, description: "Whether to count words in the entity" }),
 });
 
 /**
  * Attributed score per HTML entity
  */
 const htmlType = Type.Record(Type.String(), htmlEntity, {
+  description: "Attributed score per HTML entity",
   default: {
     br: { score: 0, countWords: true },
     code: { score: 5, countWords: false },
@@ -53,7 +54,7 @@ const htmlType = Type.Record(Type.String(), htmlEntity, {
 const rewardsType = Type.Object(
   {
     html: htmlType,
-    wordValue: Type.Number({ default: 0.1 }),
+    wordValue: Type.Number({ default: 0.1, description: "Value multiplier for each word" }),
   },
   { default: {} }
 );
@@ -66,11 +67,16 @@ export const formattingEvaluatorConfigurationType = Type.Object(
     multipliers: Type.Transform(
       Type.Array(
         Type.Object({
-          role: Type.Array(commentType, { minItems: 1 }),
-          multiplier: Type.Number(),
+          role: Type.Array(commentType, {
+            minItems: 1,
+            description: "The list of roles this multiplier applies to",
+            examples: ['["PULL_ASSIGNEE", "PULL_AUTHOR", "PULL_COLLABORATOR"]'],
+          }),
+          multiplier: Type.Number({ examples: ["1"], description: "Multiplier for the given list of roles" }),
           rewards: rewardsType,
         }),
         {
+          description: "Multipliers applied to different parts of the comment according the role of the author",
           default: [
             {
               role: ["ISSUE_SPECIFICATION"],
@@ -140,7 +146,11 @@ export const formattingEvaluatorConfigurationType = Type.Object(
       .Encode((value) => {
         return value;
       }),
-    wordCountExponent: Type.Number({ default: 0.85 }),
+    wordCountExponent: Type.Number({
+      default: 0.85,
+      description: "Exponent applied to the word count total",
+      examples: ["0.85"],
+    }),
   },
   { default: {} }
 );

src/configuration/github-comment-config.ts

@@ -5,11 +5,14 @@ export const githubCommentConfigurationType = Type.Object(
     /**
      * Enables posting to the related GitHub Issue
      */
-    post: Type.Boolean({ default: true }),
+    post: Type.Boolean({ default: true, description: "Enables posting to the related GitHub Issue" }),
     /**
      * Enables debug by creating a local html file of the rendered comment
      */
-    debug: Type.Boolean({ default: false }),
+    debug: Type.Boolean({
+      default: false,
+      description: "Enables debug by creating a local html file of the rendered comment",
+    }),
   },
   { default: {} }
 );

src/configuration/user-extractor-config.ts

@@ -4,7 +4,10 @@ export const userExtractorConfigurationType = Type.Object({
   /**
    * Is the task redeemable, e.g. can the user collect the bounty?
    */
-  redeemTask: Type.Boolean({ default: true }),
+  redeemTask: Type.Boolean({
+    default: true,
+    description: "Is the task redeemable, e.g. can the user collect the bounty?",
+  }),
 });
 
 export type UserExtractorConfiguration = Static<typeof userExtractorConfigurationType>;

src/types/plugin-input.ts

@@ -14,11 +14,14 @@ export const pluginSettingsSchema = T.Object(
     /**
      * Network ID to run in, default to 100
      */
-    evmNetworkId: T.Number({ default: 100 }),
+    evmNetworkId: T.Number({ default: 100, description: "Network ID to run in, default to 100", examples: ["100"] }),
     /**
      * The encrypted key to use for permit generation
      */
-    evmPrivateEncrypted: T.String(),
+    evmPrivateEncrypted: T.String({
+      description: "The encrypted key to use for permit generation",
+      examples: ["0x000..."],
+    }),
     /**
      * Reward token for ERC20 permits, default WXDAI for gnosis chain
      */
@@ -28,11 +31,17 @@ export const pluginSettingsSchema = T.Object(
         /**
          * Optionally specify a file to write the results in
          */
-        file: T.Optional(T.String()),
+        file: T.Optional(
+          T.String({ description: "Specify a file to write the results in", examples: ["./result.json"] })
+        ),
         /**
          * If set to false, the plugin runs even if the price label is missing, and will evaluate comments.
          */
-        requirePriceLabel: T.Boolean({ default: true }),
+        requirePriceLabel: T.Boolean({
+          default: true,
+          description:
+            "If set to false, the plugin runs even if the price label is missing, and will evaluate comments.",
+        }),
         limitRewards: T.Boolean({
           default: true,
           description: "Should the rewards of non-assignees be limited to the task reward?",