feat(@schematics/angular): add environments generation schematic

A schematic has been added that will allow the generation of environment files
for all existing configurations within a project. The `fileReplacements` option
will also be setup to allow the replacement of the appropriate environment file.
Environment files themselves do not provide any special behavior beyond
that of other application TypeScript files and rely on the `fileReplacements`
option for build-time behavior. The schematic will skip generating environment files
for configurations that already have an appropriately named environment file. The
`fileReplacements` option addition will also be skipped if an appropriate entry
is already present.

packages/schematics/angular/collection.json

@@ -115,6 +115,11 @@
       "factory": "./web-worker",
       "schema": "./web-worker/schema.json",
       "description": "Create a Web Worker."
+    },
+    "environments": {
+      "factory": "./environments",
+      "schema": "./environments/schema.json",
+      "description": "Generate project environment files."
     }
   }
 }

packages/schematics/angular/environments/index.ts

@@ -0,0 +1,147 @@
+/**
+ * @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.io/license
+ */
+
+import { Rule, SchematicsException, chain } from '@angular-devkit/schematics';
+import { AngularBuilder, TargetDefinition, updateWorkspace } from '@schematics/angular/utility';
+import { posix as path } from 'path';
+import { Schema as EnvironmentOptions } from './schema';
+
+const ENVIRONMENTS_DIRECTORY = 'environments';
+const ENVIRONMENT_FILE_CONTENT = 'export const environment = {};\n';
+
+export default function (options: EnvironmentOptions): Rule {
+  return updateWorkspace((workspace) => {
+    const project = workspace.projects.get(options.project);
+    if (!project) {
+      throw new SchematicsException(`Project name "${options.project}" doesn't not exist.`);
+    }
+
+    const type = project.extensions['projectType'];
+    if (type !== 'application') {
+      return log(
+        'error',
+        'Only application project types are support by this schematic.' + type
+          ? ` Project "${options.project}" has a "projectType" of "${type}".`
+          : ` Project "${options.project}" has no "projectType" defined.`,
+      );
+    }
+
+    const buildTarget = project.targets.get('build');
+    if (!buildTarget) {
+      return log(
+        'error',
+        `No "build" target found for project "${options.project}".` +
+          ' A "build" target is required to generate environment files.',
+      );
+    }
+
+    const serverTarget = project.targets.get('server');
+
+    const sourceRoot = project.sourceRoot ?? path.join(project.root, 'src');
+
+    // The generator needs to be iterated prior to returning to ensure all workspace changes that occur
+    // within the generator are present for `updateWorkspace` when it writes the workspace file.
+    return chain([
+      ...generateConfigurationEnvironments(buildTarget, serverTarget, sourceRoot, options.project),
+    ]);
+  });
+}
+
+function createIfMissing(path: string): Rule {
+  return (tree, context) => {
+    if (tree.exists(path)) {
+      context.logger.info(`Skipping creation of already existing environment file "${path}".`);
+    } else {
+      tree.create(path, ENVIRONMENT_FILE_CONTENT);
+    }
+  };
+}
+
+function log(type: 'info' | 'warn' | 'error', text: string): Rule {
+  return (_, context) => context.logger[type](text);
+}
+
+function* generateConfigurationEnvironments(
+  buildTarget: TargetDefinition,
+  serverTarget: TargetDefinition | undefined,
+  sourceRoot: string,
+  projectName: string,
+): Iterable<Rule> {
+  if (!buildTarget.builder.startsWith(AngularBuilder.Browser)) {
+    yield log(
+      'warn',
+      `"build" target found for project "${projectName}" has a third-party builder "${buildTarget.builder}".` +
+        ' The generated project options may not be compatible with this builder.',
+    );
+  }
+
+  if (serverTarget && !serverTarget.builder.startsWith(AngularBuilder.Server)) {
+    yield log(
+      'warn',
+      `"server" target found for project "${projectName}" has a third-party builder "${buildTarget.builder}".` +
+        ' The generated project options may not be compatible with this builder.',
+    );
+  }
+
+  // Create default environment file
+  const defaultFilePath = path.join(sourceRoot, ENVIRONMENTS_DIRECTORY, 'environment.ts');
+  yield createIfMissing(defaultFilePath);
+
+  const configurationEntries = [
+    ...Object.entries(buildTarget.configurations ?? {}),
+    ...Object.entries(serverTarget?.configurations ?? {}),
+  ];
+
+  const addedFiles = new Set<string>();
+  for (const [name, configurationOptions] of configurationEntries) {
+    if (!configurationOptions) {
+      // Invalid configuration
+      continue;
+    }
+
+    // Default configuration will use the default environment file
+    if (name === buildTarget.defaultConfiguration) {
+      continue;
+    }
+
+    const configurationFilePath = path.join(
+      sourceRoot,
+      ENVIRONMENTS_DIRECTORY,
+      `environment.${name}.ts`,
+    );
+
+    // Add file replacement option entry for the configuration environment file
+    const replacements = (configurationOptions['fileReplacements'] ??= []) as {
+      replace: string;
+      with: string;
+    }[];
+    const existing = replacements.find((value) => value.replace === defaultFilePath);
+    if (existing) {
+      if (existing.with === configurationFilePath) {
+        yield log(
+          'info',
+          `Skipping addition of already existing file replacements option for "${defaultFilePath}" to "${configurationFilePath}".`,
+        );
+      } else {
+        yield log(
+          'warn',
+          `Configuration "${name}" has a file replacements option for "${defaultFilePath}" but with a different replacement.` +
+            ` Expected "${configurationFilePath}" but found "${existing.with}". This may result in unexpected build behavior.`,
+        );
+      }
+    } else {
+      replacements.push({ replace: defaultFilePath, with: configurationFilePath });
+    }
+
+    // Create configuration specific environment file if not already added
+    if (!addedFiles.has(configurationFilePath)) {
+      addedFiles.add(configurationFilePath);
+      yield createIfMissing(configurationFilePath);
+    }
+  }
+}

packages/schematics/angular/environments/index_spec.ts

@@ -0,0 +1,174 @@
+/**
+ * @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.io/license
+ */
+
+import { SchematicTestRunner, UnitTestTree } from '@angular-devkit/schematics/testing';
+import { Schema as ApplicationOptions } from '../application/schema';
+import { Schema as WorkspaceOptions } from '../workspace/schema';
+import { Schema as EnvironmentOptions } from './schema';
+
+describe('Application Schematic', () => {
+  const schematicRunner = new SchematicTestRunner(
+    '@schematics/angular',
+    require.resolve('../collection.json'),
+  );
+
+  const workspaceOptions: WorkspaceOptions = {
+    name: 'workspace',
+    newProjectRoot: 'projects',
+    version: '15.0.0',
+  };
+
+  const defaultOptions: EnvironmentOptions = {
+    project: 'foo',
+  };
+
+  const defaultAppOptions: ApplicationOptions = {
+    name: 'foo',
+    inlineStyle: true,
+    inlineTemplate: true,
+    routing: false,
+    skipPackageJson: false,
+    minimal: true,
+  };
+
+  let applicationTree: UnitTestTree;
+  const messages: string[] = [];
+  schematicRunner.logger.subscribe((x) => messages.push(x.message));
+
+  function runEnvironmentsSchematic(): Promise<UnitTestTree> {
+    return schematicRunner.runSchematic('environments', defaultOptions, applicationTree);
+  }
+
+  beforeEach(async () => {
+    messages.length = 0;
+    const workspaceTree = await schematicRunner.runSchematic('workspace', workspaceOptions);
+    applicationTree = await schematicRunner.runSchematic(
+      'application',
+      defaultAppOptions,
+      workspaceTree,
+    );
+  });
+
+  it('should create a default environment typescript file', async () => {
+    const tree = await runEnvironmentsSchematic();
+    expect(tree.readText('projects/foo/src/environments/environment.ts')).toEqual(
+      'export const environment = {};\n',
+    );
+  });
+
+  it('should create a development configuration environment typescript file', async () => {
+    const tree = await runEnvironmentsSchematic();
+    expect(tree.readText('projects/foo/src/environments/environment.development.ts')).toEqual(
+      'export const environment = {};\n',
+    );
+  });
+
+  it('should create environment typescript files for additional configurations', async () => {
+    const initialWorkspace = JSON.parse(applicationTree.readContent('/angular.json'));
+    initialWorkspace.projects.foo.architect.build.configurations.staging = {};
+    applicationTree.overwrite('/angular.json', JSON.stringify(initialWorkspace));
+
+    const tree = await runEnvironmentsSchematic();
+    expect(tree.readText('projects/foo/src/environments/environment.development.ts')).toEqual(
+      'export const environment = {};\n',
+    );
+
+    expect(tree.readText('projects/foo/src/environments/environment.staging.ts')).toEqual(
+      'export const environment = {};\n',
+    );
+  });
+
+  it('should update the angular.json file replacements option for the development configuration', async () => {
+    const tree = await runEnvironmentsSchematic();
+    const workspace = JSON.parse(tree.readContent('/angular.json'));
+
+    const developmentConfiguration =
+      workspace.projects.foo.architect.build.configurations.development;
+    expect(developmentConfiguration).toEqual(
+      jasmine.objectContaining({
+        fileReplacements: [
+          {
+            replace: 'projects/foo/src/environments/environment.ts',
+            with: 'projects/foo/src/environments/environment.development.ts',
+          },
+        ],
+      }),
+    );
+  });
+
+  it('should update the angular.json file replacements option for additional configurations', async () => {
+    const initialWorkspace = JSON.parse(applicationTree.readContent('/angular.json'));
+    initialWorkspace.projects.foo.architect.build.configurations.staging = {};
+    applicationTree.overwrite('/angular.json', JSON.stringify(initialWorkspace));
+
+    const tree = await runEnvironmentsSchematic();
+    const workspace = JSON.parse(tree.readContent('/angular.json'));
+
+    const developmentConfiguration =
+      workspace.projects.foo.architect.build.configurations.development;
+    expect(developmentConfiguration).toEqual(
+      jasmine.objectContaining({
+        fileReplacements: [
+          {
+            replace: 'projects/foo/src/environments/environment.ts',
+            with: 'projects/foo/src/environments/environment.development.ts',
+          },
+        ],
+      }),
+    );
+
+    const stagingConfiguration = workspace.projects.foo.architect.build.configurations.staging;
+    expect(stagingConfiguration).toEqual(
+      jasmine.objectContaining({
+        fileReplacements: [
+          {
+            replace: 'projects/foo/src/environments/environment.ts',
+            with: 'projects/foo/src/environments/environment.staging.ts',
+          },
+        ],
+      }),
+    );
+  });
+
+  it('should update the angular.json file replacements option for server configurations', async () => {
+    await schematicRunner.runSchematic(
+      'universal',
+      { project: 'foo', skipInstall: true },
+      applicationTree,
+    );
+
+    const tree = await runEnvironmentsSchematic();
+    const workspace = JSON.parse(tree.readContent('/angular.json'));
+
+    const developmentConfiguration =
+      workspace.projects.foo.architect.build.configurations.development;
+    expect(developmentConfiguration).toEqual(
+      jasmine.objectContaining({
+        fileReplacements: [
+          {
+            replace: 'projects/foo/src/environments/environment.ts',
+            with: 'projects/foo/src/environments/environment.development.ts',
+          },
+        ],
+      }),
+    );
+
+    const serverDevelopmentConfiguration =
+      workspace.projects.foo.architect.server.configurations.development;
+    expect(serverDevelopmentConfiguration).toEqual(
+      jasmine.objectContaining({
+        fileReplacements: [
+          {
+            replace: 'projects/foo/src/environments/environment.ts',
+            with: 'projects/foo/src/environments/environment.development.ts',
+          },
+        ],
+      }),
+    );
+  });
+});

packages/schematics/angular/environments/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsAngularEnvironment",
+  "title": "Angular Environments Options Schema",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Generates and configures environment files for a project.",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The name of the project.",
+      "$default": {
+        "$source": "projectName"
+      }
+    }
+  },
+  "required": ["project"]
+}