Add description property to wireit script configs

schema.json

@@ -8,6 +8,10 @@
         "markdownDescription": "The wireit config for the npm script with this name.\n\nThe npm script should just run `wireit` with no args and its actual command should be put in the `command` property of this object.\n\nFor more info see: https://github.com/google/wireit#cleaning-output",
         "additionalProperties": true,
         "properties": {
+          "description": {
+            "markdownDescription": "A human-readable description of what this script does.\n\nFor example:\n\n```json\n\"description\": \"Compile TypeScript sources to JavaScript\"\n```",
+            "type": "string"
+          },
           "clean": {
             "markdownDescription": "By default, `output` files are deleted before the command is run.\n\nSet `clean` to false to prevent this.\n\nSome commands, like `tsc --build`, have their own incremental run logic and only write those output files that have changed. In that case, it can be beneficial to only delete output files when one of the input files has been deleted. In that case, set `clean` to \"if-file-deleted\".\n\nFor more info see: https://github.com/google/wireit#cleaning-output",
             "enum": [true, false, "if-file-deleted"]

src/analyzer.ts

@@ -503,6 +503,7 @@ export class Analyzer {
       declaringFile: packageJson.jsonFile,
       services: [],
       env: {},
+      description: undefined,
     };
     Object.assign(placeholder, remainingConfig);
   }
@@ -632,6 +633,11 @@ export class Analyzer {
     );
 
     const env = this.#processEnv(placeholder, packageJson, syntaxInfo, command);
+    const description = this.#processDescription(
+      placeholder,
+      packageJson,
+      syntaxInfo,
+    );
 
     if (placeholder.failures.length > 0) {
       // A script with locally-determined errors doesn't get upgraded to
@@ -658,6 +664,7 @@ export class Analyzer {
       declaringFile: packageJson.jsonFile,
       services: [],
       env,
+      description,
     };
     Object.assign(placeholder, remainingConfig);
   }
@@ -945,6 +952,39 @@ export class Analyzer {
     return defaultValue;
   }
 
+  #processDescription(
+    placeholder: UnvalidatedConfig,
+    packageJson: PackageJson,
+    syntaxInfo: ScriptSyntaxInfo,
+  ): string | undefined {
+    if (syntaxInfo.wireitConfigNode == null) {
+      return undefined;
+    }
+    const node = findNodeAtLocation(syntaxInfo.wireitConfigNode, [
+      'description',
+    ]);
+    if (node === undefined) {
+      return undefined;
+    }
+    if (typeof node.value === 'string') {
+      return node.value;
+    }
+    placeholder.failures.push({
+      type: 'failure',
+      reason: 'invalid-config-syntax',
+      script: placeholder,
+      diagnostic: {
+        severity: 'error',
+        message: `Must be a string`,
+        location: {
+          file: packageJson.jsonFile,
+          range: {length: node.length, offset: node.offset},
+        },
+      },
+    });
+    return undefined;
+  }
+
   #processFiles(
     placeholder: UnvalidatedConfig,
     packageJson: PackageJson,

src/config.ts

@@ -207,6 +207,11 @@ interface BaseScriptConfig extends ScriptReference {
    */
   configAstNode: NamedAstNode | undefined;
 
+  /**
+   * A human-readable description of what this script does.
+   */
+  description: string | undefined;
+
   /** The parsed JSON file that declared this script. */
   declaringFile: JsonFile;
   failures: Failure[];

src/test/json-schema.test.ts

@@ -82,6 +82,7 @@ test('a script with all fields set is valid', () => {
     wireit: {
       a: {
         command: 'b',
+        description: 'A description.',
         dependencies: ['c', {script: 'c', cascade: false}],
         files: ['d'],
         output: ['e'],
@@ -266,4 +267,29 @@ test('dependencies[i].cascade must be boolean', () => {
   );
 });
 
+test('description is valid when set to a string', () => {
+  shouldValidate({
+    wireit: {
+      a: {
+        command: 'b',
+        description: 'A human-readable description of this script.',
+      },
+    },
+  });
+});
+
+test('description must be a string', () => {
+  expectValidationErrors(
+    {
+      wireit: {
+        a: {
+          command: 'b',
+          description: 123,
+        },
+      },
+    },
+    ['instance.wireit.a.description is not of a type(s) string'],
+  );
+});
+
 test.run();

src/test/util/package-json.ts

@@ -16,6 +16,7 @@ export interface PackageJson {
   wireit?: {
     [scriptName: string]: {
       command?: string;
+      description?: string;
       dependencies?: Array<string | {script: string; cascade?: boolean}>;
       files?: string[];
       output?: string[];