fix(core): show target description, add metadata to schema, and docum… (#27131)

…ent it

<!-- Please make sure you have read the submission guidelines before
posting an PR -->
<!--
https://github.com/nrwl/nx/blob/master/CONTRIBUTING.md#-submitting-a-pr
-->

<!-- Please make sure that your commit message follows our format -->
<!-- Example: `fix(nx): must begin with lowercase` -->

<!-- If this is a particularly complex change or feature addition, you
can request a dedicated Nx release for this pull request branch. Mention
someone from the Nx team or the `@nrwl/nx-pipelines-reviewers` and they
will confirm if the PR warrants its own release for testing purposes,
and generate it for you if appropriate. -->

## Current Behavior
<!-- This is the behavior we have today -->

Target description is not shown in the PDV.

Also, being able to set a description in `project.json` is not in the
schema nor is it documented.

## Expected Behavior
<!-- This is the behavior we should expect with the changes in this PR
-->

Target descriptions are shown in the PDV.

Also, being able to set a description in `project.json` is in the schema
and documented on
https://nx-dev-git-metadata-docs-nrwl.vercel.app/project-configuration#target-metadata


![image](https://github.com/user-attachments/assets/2037eca8-d516-4513-81fd-12b8384a9411)


## Related Issue(s)
<!-- Please link the issue being fixed so it gets closed when this is
merged. -->

Fixes https://github.com/nrwl/nx/issues/19355

docs/shared/reference/project-configuration.md

@@ -650,6 +650,23 @@ In the case of an explicit target using an executor, you can specify the executo
 }
 ```
 
+### Target Metadata
+
+You can add additional metadata to be attached to a target. For example, you can provide a description stating what the
+target does:
+
+```jsonc {% fileName="project.json" %}
+{
+  "targets": {
+    "build": {
+      "metadata": {
+        "description": "Build the application for production"
+      }
+    }
+  }
+}
+```
+
 ## Project Metadata
 
 The following properties describe the project as a whole.
@@ -769,7 +786,21 @@ An implicit dependency could also be a glob pattern:
 {% /tab %}
 {% /tabs %}
 
-### Including package.json files as projects in the graph
+### Metadata
+
+You can add additional metadata to be attached to the project. For example, you can provide a description for your
+project:
+
+```jsonc {% fileName="project.json" %}
+{
+  "name": "admin",
+  "metadata": {
+    "description": "This is the admin application"
+  }
+}
+```
+
+## Including package.json files as projects in the graph
 
 Any `package.json` file that is referenced by the `workspaces` property in the root `package.json` file will be included as a project in the graph. If you are using Lerna, projects defined in `lerna.json` will be included. If you are using pnpm, projects defined in `pnpm-workspace.yml` will be included.
 

graph/ui-project-details/src/lib/target-configuration-details/target-configuration-details.tsx

@@ -103,6 +103,25 @@ export default function TargetConfigurationDetails({
       {/* body */}
       {!collapsed && (
         <div className="p-4 text-base">
+          {targetConfiguration.metadata?.description && (
+            <div className="group mb-4">
+              <h4 className="mb-4">
+                <span className="font-medium">Description</span>
+                <span className="mb-1 ml-2 hidden group-hover:inline">
+                  <CopyToClipboardButton
+                    text={`"metadata": ${JSON.stringify({
+                      description: targetConfiguration.metadata?.description,
+                    })}`}
+                    tooltipText="Copy Description"
+                  />
+                </span>
+              </h4>
+              <p className="pl-5">
+                {targetConfiguration.metadata?.description}
+              </p>
+            </div>
+          )}
+
           <div className="group mb-4">
             <h4 className="mb-4">
               <TargetExecutorTitle {...displayHeader} />

packages/nx/schemas/project-schema.json

@@ -115,8 +115,12 @@
                       "required": ["target"],
                       "not": {
                         "anyOf": [
-                          { "required": ["projects"] },
+                          {
-                          { "required": ["dependencies"] }
+                            "required": ["projects"]
+                          },
+                          {
+                            "required": ["dependencies"]
+                          }
                         ]
                       }
                     }
@@ -138,6 +142,17 @@
             "type": "boolean",
             "default": true,
             "description": "Whether this target can be run in parallel with other tasks"
+          },
+          "metadata": {
+            "type": "object",
+            "description": "Metadata about the target",
+            "properties": {
+              "description": {
+                "type": "string",
+                "description": "A description of the target"
+              }
+            },
+            "additionalProperties": true
           }
         }
       }
@@ -154,6 +169,17 @@
         "type": "string"
       }
     },
+    "metadata": {
+      "type": "object",
+      "description": "Metadata about the project.",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "A description of the project."
+        }
+      },
+      "additionalProperties": true
+    },
     "release": {
       "type": "object",
       "description": "Configuration for the nx release commands.",
@@ -205,7 +231,9 @@
                   {
                     "type": "array",
                     "description": "The projects that the targets belong to.",
-                    "items": { "type": "string" }
+                    "items": {
+                      "type": "string"
+                    }
                   }
                 ]
               },
@@ -229,8 +257,12 @@
                 "required": ["input"],
                 "not": {
                   "anyOf": [
-                    { "required": ["projects"] },
+                    {
-                    { "required": ["dependencies"] }
+                      "required": ["projects"]
+                    },
+                    {
+                      "required": ["dependencies"]
+                    }
                   ]
                 }
               }
@@ -262,7 +294,9 @@
             "properties": {
               "externalDependencies": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "The list of external dependencies that our target depends on for `nx:run-commands` and community plugins."
               }
             },