fix(@angular/cli): explain how to pick a project when a schematic cannot determine one

when project can't be resolved from cwd, like at root of workspace with no root project, schematics fail with raw `Data path "" must have required property 'project'` from schema validation
now that error is replaced with message that says to pass `--project` or cd into project and lists available projects like architect commands do, empty workspace gets hint to generate application or libary first

Fixes #25402

Author: thekhegay

packages/angular/cli/src/command-builder/schematics-command-module.ts

@@ -6,7 +6,15 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { JsonValue, normalize as devkitNormalize, schema } from '@angular-devkit/core';
+import {
+  JsonObject,
+  JsonValue,
+  normalize as devkitNormalize,
+  isJsonArray,
+  isJsonObject,
+  schema,
+  strings,
+} from '@angular-devkit/core';
 import { Collection, UnsuccessfulWorkflowExecution, formats } from '@angular-devkit/schematics';
 import {
   FileSystemCollectionDescription,
@@ -17,13 +25,14 @@ import { relative } from 'node:path';
 import { Argv } from 'yargs';
 import { isPackageNameSafeForAnalytics } from '../analytics/analytics';
 import { EventCustomDimension } from '../analytics/analytics-parameters';
-import { getProjectByCwd, getSchematicDefaults } from '../utilities/config';
+import { AngularWorkspace, getProjectByCwd, getSchematicDefaults } from '../utilities/config';
 import { assertIsError } from '../utilities/error';
 import { memoize } from '../utilities/memoize';
 import { formatFiles } from '../utilities/prettier';
 import { isTTY } from '../utilities/tty';
 import {
   CommandModule,
+  CommandModuleError,
   CommandModuleImplementation,
   CommandScope,
   Options,
@@ -131,6 +140,20 @@ export abstract class SchematicsCommandModule
             ...current,
           };
         },
+        // Fail before smart defaults and prompts are applied when a required option relies on the
+        // `projectName` smart default and the project cannot be determined.
+        (schematic, current) => {
+          const { workspace } = this.context;
+          const message =
+            workspace && this.getProjectName() === undefined
+              ? getMissingProjectMessage(workspace, schematic.schemaJson, current)
+              : undefined;
+          if (message) {
+            throw new CommandModuleError(message);
+          }
+
+          return current ?? {};
+        },
       ],
       engineHostCreator: (options) => new SchematicEngineHost(options.resolvePaths),
     });
@@ -427,3 +450,60 @@ export abstract class SchematicsCommandModule
         [import.meta.dirname, process.cwd()];
   }
 }
+
+/**
+ * Returns an error message when a schematic requires an option that uses the `projectName` smart
+ * default, the option has no value and the project cannot be determined from the current working
+ * directory. Otherwise schema validation fails later with a generic "must have required property"
+ * error, after prompting for other options.
+ */
+export function getMissingProjectMessage(
+  workspace: AngularWorkspace,
+  schemaJson: JsonObject | undefined,
+  options: Record<string, unknown> | null,
+): string | undefined {
+  if (!schemaJson) {
+    return undefined;
+  }
+
+  const { properties, required } = schemaJson;
+  if (!isJsonObject(properties) || !isJsonArray(required)) {
+    return undefined;
+  }
+
+  const optionName = Object.keys(properties).find((name) => {
+    const property = properties[name];
+
+    return (
+      required.includes(name) &&
+      options?.[name] === undefined &&
+      isJsonObject(property) &&
+      isJsonObject(property.$default) &&
+      property.$default.$source === 'projectName' &&
+      property['x-prompt'] === undefined
+    );
+  });
+
+  if (optionName === undefined) {
+    return undefined;
+  }
+
+  if (workspace.projects.size === 0) {
+    return (
+      'Cannot determine project for command.\n' +
+      'This workspace does not contain any projects. ' +
+      'Run "ng generate application" or "ng generate library" to create one.'
+    );
+  }
+
+  return (
+    'Cannot determine project for command.\n' +
+    'This is a multi-project workspace and the current working directory is not inside a single ' +
+    `project. Use the "--${strings.dasherize(optionName)}" option to specify a project or change ` +
+    'the current working directory to a project directory.\n\n' +
+    `Available projects are:\n${[...workspace.projects.keys()]
+      .sort()
+      .map((p) => `- ${p}`)
+      .join('\n')}`
+  );
+}

packages/angular/cli/src/command-builder/schematics-command-module_spec.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { JsonObject, workspaces } from '@angular-devkit/core';
+import { AngularWorkspace } from '../utilities/config';
+import { getMissingProjectMessage } from './schematics-command-module';
+
+describe('getMissingProjectMessage', () => {
+  const projectOption = { type: 'string', $default: { $source: 'projectName' } };
+  const schemaJson: JsonObject = {
+    type: 'object',
+    properties: { name: { type: 'string' }, project: projectOption },
+    required: ['name', 'project'],
+  };
+
+  function createWorkspace(...projectNames: string[]): AngularWorkspace {
+    const projects = new workspaces.ProjectDefinitionCollection();
+    for (const name of projectNames) {
+      projects.add({ name, root: `projects/${name}` });
+    }
+
+    return new AngularWorkspace({ extensions: {}, projects }, '/angular.json');
+  }
+
+  it('should list the available projects when the project cannot be determined', () => {
+    expect(getMissingProjectMessage(createWorkspace('second', 'first'), schemaJson, {})).toBe(
+      'Cannot determine project for command.\n' +
+        'This is a multi-project workspace and the current working directory is not inside a ' +
+        'single project. Use the "--project" option to specify a project or change the current ' +
+        'working directory to a project directory.\n\n' +
+        'Available projects are:\n- first\n- second',
+    );
+  });
+
+  it('should explain how to create a project when the workspace has none', () => {
+    expect(getMissingProjectMessage(createWorkspace(), schemaJson, {})).toBe(
+      'Cannot determine project for command.\n' +
+        'This workspace does not contain any projects. ' +
+        'Run "ng generate application" or "ng generate library" to create one.',
+    );
+  });
+
+  it('should use the name of the option that relies on the smart default', () => {
+    const message = getMissingProjectMessage(
+      createWorkspace('first', 'second'),
+      { properties: { targetProject: projectOption }, required: ['targetProject'] },
+      {},
+    );
+
+    expect(message).toContain('Use the "--target-project" option');
+  });
+
+  it('should not return a message when the option has a value', () => {
+    expect(
+      getMissingProjectMessage(createWorkspace('first', 'second'), schemaJson, {
+        project: 'first',
+      }),
+    ).toBeUndefined();
+  });
+
+  it('should not return a message when the option is not required', () => {
+    expect(
+      getMissingProjectMessage(
+        createWorkspace('first', 'second'),
+        { ...schemaJson, required: ['name'] },
+        {},
+      ),
+    ).toBeUndefined();
+  });
+
+  it('should not return a message when the option does not use the smart default', () => {
+    expect(
+      getMissingProjectMessage(
+        createWorkspace('first', 'second'),
+        { ...schemaJson, properties: { project: { type: 'string' } } },
+        {},
+      ),
+    ).toBeUndefined();
+  });
+
+  it('should not return a message when the option can be prompted for', () => {
+    expect(
+      getMissingProjectMessage(
+        createWorkspace('first', 'second'),
+        {
+          ...schemaJson,
+          properties: { project: { ...projectOption, 'x-prompt': 'Which project?' } },
+        },
+        {},
+      ),
+    ).toBeUndefined();
+  });
+});

tests/e2e/tests/commands/project-cannot-be-determined-by-cwd.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { join } from 'node:path';
-import { execAndWaitForOutputToMatch, ng } from '../../utils/process';
+import { execAndCaptureError, execAndWaitForOutputToMatch, ng } from '../../utils/process';
 import { updateJsonFile } from '../../utils/project';
 import { expectToFail } from '../../utils/utils';
 
@@ -23,6 +23,28 @@ export default async function () {
     const { message } = await expectToFail(() => ng('build'));
     assert.match(message, new RegExp(errorMessage));
 
+    // Schematics that require a project should explain how to select one
+    const { message: generateMessage } = await expectToFail(() =>
+      ng('generate', 'component', 'foo'),
+    );
+    assert.match(generateMessage, /Use the "--project" option to specify a project/);
+    assert.match(generateMessage, /Available projects are:\n- second-app\n- third-app/);
+
+    // The project is checked before prompting for other options
+    const { message: interactiveMessage } = await execAndCaptureError(
+      'ng',
+      ['generate', 'component'],
+      {
+        ...process.env,
+        NG_FORCE_TTY: '1',
+        NG_CLI_ANALYTICS: 'false',
+        NG_FORCE_AUTOCOMPLETE: 'false',
+      },
+      'foo\n',
+    );
+    assert.match(interactiveMessage, /Use the "--project" option to specify a project/);
+    assert.doesNotMatch(interactiveMessage, /What name would you like to use for the component/);
+
     // Help should still work
     await execAndWaitForOutputToMatch('ng', ['build', '--help'], /--configuration/);
 
@@ -31,8 +53,21 @@ export default async function () {
 
     process.chdir(join(startCwd, 'projects/second-app'));
     await ng('build', '--configuration=development');
+    await ng('generate', 'component', 'foo', '--dry-run');
   } finally {
     // Restore path
     process.chdir(startCwd);
   }
+
+  // A project from the workspace schematic options is used and other validation errors are kept
+  await updateJsonFile('angular.json', (workspaceJson) => {
+    workspaceJson.schematics ??= {};
+    workspaceJson.schematics['@schematics/angular:component'] = { project: 'second-app' };
+  });
+  const { message: selectorMessage } = await expectToFail(() =>
+    ng('generate', 'component', 'foo', '--selector=1foo'),
+  );
+  assert.match(selectorMessage, /must match format "html-selector"/);
+  assert.doesNotMatch(selectorMessage, /Cannot determine project/);
+  await ng('generate', 'component', 'foo', '--dry-run');
 }