feat(core): ability to save task graph to a file when running --graph

docs/generated/cli/affected.md

@@ -105,11 +105,11 @@ Change the way Nx is calculating the affected command by providing directly chan
 
 ### graph
 
-Type: `boolean`
+Type: `string`
 
 Default: `false`
 
-Show the task graph of the command
+Show the task graph of the command. Pass a file path to save the graph data instead of viewing it in the browser.
 
 ### head
 

docs/generated/cli/exec.md

@@ -31,11 +31,11 @@ Exclude certain projects from being processed
 
 ### graph
 
-Type: `boolean`
+Type: `string`
 
 Default: `false`
 
-Show the task graph of the command
+Show the task graph of the command. Pass a file path to save the graph data instead of viewing it in the browser.
 
 ### nx-bail
 

docs/generated/cli/run-many.md

@@ -83,11 +83,11 @@ Exclude certain projects from being processed
 
 ### graph
 
-Type: `boolean`
+Type: `string`
 
 Default: `false`
 
-Show the task graph of the command
+Show the task graph of the command. Pass a file path to save the graph data instead of viewing it in the browser.
 
 ### help
 

docs/generated/packages/nx/documents/affected.md

@@ -105,11 +105,11 @@ Change the way Nx is calculating the affected command by providing directly chan
 
 ### graph
 
-Type: `boolean`
+Type: `string`
 
 Default: `false`
 
-Show the task graph of the command
+Show the task graph of the command. Pass a file path to save the graph data instead of viewing it in the browser.
 
 ### head
 

docs/generated/packages/nx/documents/exec.md

@@ -31,11 +31,11 @@ Exclude certain projects from being processed
 
 ### graph
 
-Type: `boolean`
+Type: `string`
 
 Default: `false`
 
-Show the task graph of the command
+Show the task graph of the command. Pass a file path to save the graph data instead of viewing it in the browser.
 
 ### nx-bail
 

docs/generated/packages/nx/documents/run-many.md

@@ -83,11 +83,11 @@ Exclude certain projects from being processed
 
 ### graph
 
-Type: `boolean`
+Type: `string`
 
 Default: `false`
 
-Show the task graph of the command
+Show the task graph of the command. Pass a file path to save the graph data instead of viewing it in the browser.
 
 ### help
 

e2e/nx-run/src/affected-graph.test.ts

@@ -503,6 +503,14 @@ describe('Nx Affected and Graph Tests', () => {
       expect(environmentJs).toContain('"affected":[]');
     });
 
+    it('graph should output valid json when stdout is specified', () => {
+      const result = runCLI(`affected -t build --graph stdout`);
+      let model;
+      expect(() => (model = JSON.parse(result))).not.toThrow();
+      expect(model).toHaveProperty('graph');
+      expect(model).toHaveProperty('tasks');
+    });
+
     it('affected:graph should include affected projects in environment file', () => {
       runCLI(`affected:graph --file=project-graph.html`);
 

packages/nx/src/command-line/affected/affected.ts

@@ -4,7 +4,10 @@ import { output } from '../../utils/output';
 import { generateGraph } from '../graph/graph';
 import { printAffected } from './print-affected';
 import { connectToNxCloudIfExplicitlyAsked } from '../connect/connect-to-nx-cloud';
-import type { NxArgs } from '../../utils/command-line-utils';
+import {
+  NxArgs,
+  readGraphFileFromGraphArg,
+} from '../../utils/command-line-utils';
 import {
   parseFiles,
   splitArgsIntoNxArgsAndOverrides,
@@ -38,7 +41,8 @@ export async function affected(
     args,
     'affected',
     {
-      printWarnings: command !== 'print-affected' && !args.plain,
+      printWarnings:
+        command !== 'print-affected' && !args.plain && args.graph !== 'stdout',
     },
     nxJson
   );
@@ -83,6 +87,7 @@ export async function affected(
         const projectsWithTarget = allProjectsWithTarget(projects, nxArgs);
         if (nxArgs.graph) {
           const projectNames = projectsWithTarget.map((t) => t.name);
+          const file = readGraphFileFromGraphArg(nxArgs);
 
           return await generateGraph(
             {
@@ -91,6 +96,7 @@ export async function affected(
               view: 'tasks',
               targets: nxArgs.targets,
               projects: projectNames,
+              file,
             },
             projectNames
           );

packages/nx/src/command-line/graph/graph.ts

@@ -187,7 +187,12 @@ export async function generateGraph(
   },
   affectedProjects: string[]
 ): Promise<void> {
-  if (Array.isArray(args.targets) && args.targets.length > 1) {
+  if (
+    Array.isArray(args.targets) &&
+    args.targets.length > 1 &&
+    args.file &&
+    !(args.file === 'stdout' || args.file.endsWith('.json'))
+  ) {
     output.warn({
       title: 'Showing Multiple Targets is not supported yet',
       bodyLines: [
@@ -246,6 +251,18 @@ export async function generateGraph(
   graph = filterGraph(graph, args.focus || null, args.exclude || []);
 
   if (args.file) {
+    // stdout is a magical constant that doesn't actually write a file
+    if (args.file === 'stdout') {
+      console.log(
+        JSON.stringify(
+          createJsonOutput(graph, args.projects, args.targets),
+          null,
+          2
+        )
+      );
+      process.exit(0);
+    }
+
     const workspaceFolder = workspaceRoot;
     const ext = extname(args.file);
     const fullFilePath = isAbsolute(args.file)
@@ -294,10 +311,20 @@ export async function generateGraph(
     } else if (ext === '.json') {
       ensureDirSync(dirname(fullFilePath));
 
-      writeJsonFile(fullFilePath, {
-        graph,
-        affectedProjects,
-        criticalPath: affectedProjects,
+      const json = createJsonOutput(graph, args.projects, args.targets);
+      json.affectedProjects = affectedProjects;
+      json.criticalPath = affectedProjects;
+
+      writeJsonFile(fullFilePath, json);
+
+      output.warn({
+        title: 'JSON output contains deprecated fields:',
+        bodyLines: [
+          '- affectedProjects',
+          '- criticalPath',
+          '',
+          'These fields will be removed in Nx 18. If you need to see which projects were affected, use `nx show projects --affected`.',
+        ],
       });
 
       output.success({
@@ -685,3 +712,47 @@ function createTaskId(
     return `${projectId}:${targetId}`;
   }
 }
+
+interface GraphJsonResponse {
+  tasks?: TaskGraph;
+  graph: ProjectGraph;
+
+  /**
+   * @deprecated To see affected projects, use `nx show projects --affected`. This will be removed in Nx 18.
+   */
+  affectedProjects?: string[];
+
+  /**
+   * @deprecated To see affected projects, use `nx show projects --affected`. This will be removed in Nx 18.
+   */
+  criticalPath?: string[];
+}
+
+function createJsonOutput(
+  graph: ProjectGraph,
+  projects: string[],
+  targets?: string[]
+): GraphJsonResponse {
+  const response: GraphJsonResponse = {
+    graph,
+  };
+
+  if (targets?.length) {
+    const nxJson = readNxJson();
+
+    const defaultDependencyConfigs = mapTargetDefaultsToDependencies(
+      nxJson.targetDefaults
+    );
+
+    response.tasks = createTaskGraph(
+      graph,
+      defaultDependencyConfigs,
+      projects,
+      targets,
+      undefined,
+      {}
+    );
+  }
+
+  return response;
+}

packages/nx/src/command-line/run-many/run-many.ts

@@ -1,5 +1,8 @@
 import { runCommand } from '../../tasks-runner/run-command';
-import type { NxArgs } from '../../utils/command-line-utils';
+import {
+  NxArgs,
+  readGraphFileFromGraphArg,
+} from '../../utils/command-line-utils';
 import { splitArgsIntoNxArgsAndOverrides } from '../../utils/command-line-utils';
 import { projectHasTarget } from '../../utils/project-graph-utils';
 import { connectToNxCloudIfExplicitlyAsked } from '../connect/connect-to-nx-cloud';
@@ -33,7 +36,7 @@ export async function runMany(
   const { nxArgs, overrides } = splitArgsIntoNxArgsAndOverrides(
     args,
     'run-many',
-    { printWarnings: true },
+    { printWarnings: args.graph !== 'stdout' },
     nxJson
   );
   if (nxArgs.verbose) {
@@ -46,6 +49,7 @@ export async function runMany(
   const projects = projectsToRun(nxArgs, projectGraph);
 
   if (nxArgs.graph) {
+    const file = readGraphFileFromGraphArg(nxArgs);
     const projectNames = projects.map((t) => t.name);
     return await generateGraph(
       {
@@ -55,6 +59,7 @@ export async function runMany(
         all: nxArgs.all,
         targets: nxArgs.targets,
         projects: projectNames,
+        file,
       },
       projectNames
     );

packages/nx/src/command-line/run/run-one.ts

@@ -1,5 +1,8 @@
 import { runCommand } from '../../tasks-runner/run-command';
-import { splitArgsIntoNxArgsAndOverrides } from '../../utils/command-line-utils';
+import {
+  readGraphFileFromGraphArg,
+  splitArgsIntoNxArgsAndOverrides,
+} from '../../utils/command-line-utils';
 import { connectToNxCloudIfExplicitlyAsked } from '../connect/connect-to-nx-cloud';
 import { performance } from 'perf_hooks';
 import {
@@ -47,7 +50,7 @@ export async function runOne(
       targets: [opts.target],
     },
     'run-one',
-    { printWarnings: true },
+    { printWarnings: args.graph !== 'stdout' },
     nxJson
   );
   if (nxArgs.verbose) {
@@ -66,6 +69,7 @@ export async function runOne(
 
   if (nxArgs.graph) {
     const projectNames = projects.map((t) => t.name);
+    const file = readGraphFileFromGraphArg(nxArgs);
 
     return await generateGraph(
       {
@@ -74,6 +78,7 @@ export async function runOne(
         view: 'tasks',
         targets: nxArgs.targets,
         projects: projectNames,
+        file,
       },
       projectNames
     );

packages/nx/src/command-line/yargs-utils/shared-options.ts

@@ -29,9 +29,16 @@ export function withRunOptions(yargs: Argv): Argv {
       hidden: true,
     })
     .option('graph', {
-      type: 'boolean',
-      describe: 'Show the task graph of the command',
+      type: 'string',
+      describe:
+        'Show the task graph of the command. Pass a file path to save the graph data instead of viewing it in the browser.',
       default: false,
+      coerce: (value) =>
+        value === 'true' || value === true
+          ? true
+          : value === 'false' || value === false
+          ? false
+          : value,
     })
     .option('verbose', {
       type: 'boolean',

packages/nx/src/utils/command-line-utils.ts

@@ -29,7 +29,7 @@ export interface NxArgs {
   plain?: boolean;
   projects?: string[];
   select?: string;
-  graph?: boolean;
+  graph?: string | boolean;
   skipNxCache?: boolean;
   outputStyle?: string;
   nxBail?: boolean;
@@ -288,8 +288,6 @@ function getUncommittedFiles(): string[] {
   return parseGitOutput(`git diff --name-only --no-renames --relative HEAD .`);
 }
 
-``;
-
 function getUntrackedFiles(): string[] {
   return parseGitOutput(`git ls-files --others --exclude-standard`);
 }
@@ -338,3 +336,9 @@ export function getProjectRoots(
 ): string[] {
   return projectNames.map((name) => nodes[name].data.root);
 }
+
+export function readGraphFileFromGraphArg({ graph }: NxArgs) {
+  return typeof graph === 'string' && graph !== 'true' && graph !== ''
+    ? graph
+    : undefined;
+}