feat(core): add initialNavigation schematic (angular#36926)

Add a schematic to update users to the new v11 `initialNavigation` options for `RouterModule`. This replaces the deprecated/removed `true`, `false`, `legacy_disabled`, and `legacy_enabled` options with the newer `enabledBlocking` and `enabledNonBlocking` options. PR Close angular#36926

Author: CaerusKaru

packages/core/schematics/BUILD.bazel

@@ -12,6 +12,7 @@ pkg_npm(
  deps = [
  "//packages/core/schematics/migrations/abstract-control-parent",
  "//packages/core/schematics/migrations/dynamic-queries",
+ "//packages/core/schematics/migrations/initial-navigation",
  "//packages/core/schematics/migrations/missing-injectable",
  "//packages/core/schematics/migrations/module-with-providers",
  "//packages/core/schematics/migrations/move-document",

packages/core/schematics/migrations.json

@@ -74,6 +74,11 @@
  "version": "11.0.0-beta",
  "description": "NavigationExtras.preserveQueryParams has been removed as of Angular version 11. This migration replaces any usages with the appropriate assignment of the queryParamsHandler key.",
  "factory": "./migrations/router-preserve-query-params/index"
+ },
+ "migration-v11-router-initial-navigation-options": {
+ "version": "11.0.0-beta",
+ "description": "Updates the `initialNavigation` property for `RouterModule.forRoot`.",
+ "factory": "./migrations/initial-navigation/index"
  }
  }
 }

packages/core/schematics/migrations/google3/BUILD.bazel

@@ -7,6 +7,8 @@ ts_library(
  visibility = ["//packages/core/schematics/test/google3:__pkg__"],
  deps = [
  "//packages/core/schematics/migrations/dynamic-queries",
+ "//packages/core/schematics/migrations/initial-navigation",
+ "//packages/core/schematics/migrations/initial-navigation/google3",
  "//packages/core/schematics/migrations/missing-injectable",
  "//packages/core/schematics/migrations/missing-injectable/google3",
  "//packages/core/schematics/migrations/navigation-extras-omissions",

packages/core/schematics/migrations/google3/initialNavigationRule.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 {RuleFailure, Rules} from 'tslint';
+import * as ts from 'typescript';
+
+import {InitialNavigationCollector} from '../initial-navigation/collector';
+import {TslintUpdateRecorder} from '../initial-navigation/google3/tslint_update_recorder';
+import {InitialNavigationTransform} from '../initial-navigation/transform';
+
+
+
+/**
+ * TSLint rule that updates RouterModule `forRoot` options to be in line with v10 updates.
+ */
+export class Rule extends Rules.TypedRule {
+ applyWithProgram(sourceFile: ts.SourceFile, program: ts.Program): RuleFailure[] {
+ const ruleName = this.ruleName;
+ const typeChecker = program.getTypeChecker();
+ const sourceFiles = program.getSourceFiles().filter(
+ s => !s.isDeclarationFile && !program.isSourceFileFromExternalLibrary(s));
+ const initialNavigationCollector = new InitialNavigationCollector(typeChecker);
+ const failures: RuleFailure[] = [];
+
+ // Analyze source files by detecting all ExtraOptions#InitialNavigation assignments
+ sourceFiles.forEach(sourceFile => initialNavigationCollector.visitNode(sourceFile));
+
+ const {assignments} = initialNavigationCollector;
+ const transformer = new InitialNavigationTransform(typeChecker, getUpdateRecorder);
+ const updateRecorders = new Map<ts.SourceFile, TslintUpdateRecorder>();
+
+ transformer.migrateInitialNavigationAssignments(Array.from(assignments));
+
+ if (updateRecorders.has(sourceFile)) {
+ failures.push(...updateRecorders.get(sourceFile)!.failures);
+ }
+
+ return failures;
+
+ /** Gets the update recorder for the specified source file. */
+ function getUpdateRecorder(sourceFile: ts.SourceFile): TslintUpdateRecorder {
+ if (updateRecorders.has(sourceFile)) {
+ return updateRecorders.get(sourceFile)!;
+ }
+ const recorder = new TslintUpdateRecorder(ruleName, sourceFile);
+ updateRecorders.set(sourceFile, recorder);
+ return recorder;
+ }
+ }
+}

packages/core/schematics/migrations/initial-navigation/BUILD.bazel

@@ -0,0 +1,19 @@
+load("//tools:defaults.bzl", "ts_library")
+
+ts_library(
+ name = "initial-navigation",
+ srcs = glob(["**/*.ts"]),
+ tsconfig = "//packages/core/schematics:tsconfig.json",
+ visibility = [
+ "//packages/core/schematics:__pkg__",
+ "//packages/core/schematics/migrations/google3:__pkg__",
+ "//packages/core/schematics/migrations/initial-navigation/google3:__pkg__",
+ "//packages/core/schematics/test:__pkg__",
+ ],
+ deps = [
+ "//packages/core/schematics/utils",
+ "@npm//@angular-devkit/schematics",
+ "@npm//@types/node",
+ "@npm//typescript",
+ ],
+)

packages/core/schematics/migrations/initial-navigation/README.md

@@ -0,0 +1,43 @@
+## initialNavigation migration
+
+Automatically migrates the `initialNavigation` property of the `RouterModule` to the newly
+available options: `enabledNonBlocking` (default), `enabledBlocking`, and `disabled`.
+
+#### Before
+```ts
+import { NgModule } from '@angular/core';
+import { RouterModule } from '@angular/router';
+
+@NgModule({
+ imports: [
+ RouterModule.forRoot(ROUTES, {initialNavigation: 'legacy_disabled'}),
+ ]
+})
+export class AppModule {
+}
+```
+
+#### After
+```ts
+import { NgModule } from '@angular/core';
+import { RouterModule } from '@angular/router';
+
+@NgModule({
+ imports: [
+ RouterModule.forRoot(ROUTES, {initialNavigation: 'disabled'}),
+ ]
+})
+export class AppModule {
+}
+```
+
+### Disclaimer
+
+The migration only covers the most common patterns where developers set the `ExtraOptions#InitialNavigation` 
+option to an outdated value. Therefore, if a user declares the option using a number of other methods, 
+e.g. shorthand notation, variable declaration, or some other crafty method, they will have to migrate 
+those options by hand. Otherwise, the compiler will error if the types are sufficiently enforced.
+
+The basic migration strategy is as follows:
+* `legacy_disabled` || `false` => `disabled`
+* `legacy_enabled` || `true` => `enabledNonBlocking` (new default)

packages/core/schematics/migrations/initial-navigation/collector.ts

@@ -0,0 +1,116 @@
+/**
+ * @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 * as ts from 'typescript';
+import {isExtraOptions, isRouterModuleForRoot} from './util';
+
+
+/** The property name for the options that need to be migrated */
+const INITIAL_NAVIGATION = 'initialNavigation';
+
+/**
+ * Visitor that walks through specified TypeScript nodes and collects all
+ * found ExtraOptions#InitialNavigation assignments.
+ */
+export class InitialNavigationCollector {
+ public assignments: Set<ts.PropertyAssignment> = new Set();
+
+ constructor(private readonly typeChecker: ts.TypeChecker) {}
+
+ visitNode(node: ts.Node) {
+ let extraOptionsLiteral: ts.ObjectLiteralExpression|null = null;
+ if (isRouterModuleForRoot(this.typeChecker, node) && node.arguments.length > 0) {
+ if (node.arguments.length === 1) {
+ return;
+ }
+
+ if (ts.isObjectLiteralExpression(node.arguments[1])) {
+ extraOptionsLiteral = node.arguments[1] as ts.ObjectLiteralExpression;
+ } else if (ts.isIdentifier(node.arguments[1])) {
+ extraOptionsLiteral =
+ this.getLiteralNeedingMigrationFromIdentifier(node.arguments[1] as ts.Identifier);
+ }
+ } else if (ts.isVariableDeclaration(node)) {
+ extraOptionsLiteral = this.getLiteralNeedingMigration(node);
+ }
+
+ if (extraOptionsLiteral !== null) {
+ this.visitExtraOptionsLiteral(extraOptionsLiteral);
+ } else {
+ // no match found, continue iteration
+ ts.forEachChild(node, n => this.visitNode(n));
+ }
+ }
+
+ visitExtraOptionsLiteral(extraOptionsLiteral: ts.ObjectLiteralExpression) {
+ for (const prop of extraOptionsLiteral.properties) {
+ if (ts.isPropertyAssignment(prop) &&
+ (ts.isIdentifier(prop.name) || ts.isStringLiteralLike(prop.name))) {
+ if (prop.name.text === INITIAL_NAVIGATION && isValidInitialNavigationValue(prop)) {
+ this.assignments.add(prop);
+ }
+ } else if (ts.isSpreadAssignment(prop) && ts.isIdentifier(prop.expression)) {
+ const literalFromSpreadAssignment =
+ this.getLiteralNeedingMigrationFromIdentifier(prop.expression);
+ if (literalFromSpreadAssignment !== null) {
+ this.visitExtraOptionsLiteral(literalFromSpreadAssignment);
+ }
+ }
+ }
+ }
+
+ private getLiteralNeedingMigrationFromIdentifier(id: ts.Identifier): ts.ObjectLiteralExpression
+ |null {
+ const symbolForIdentifier = this.typeChecker.getSymbolAtLocation(id);
+ if (symbolForIdentifier === undefined) {
+ return null;
+ }
+
+ if (symbolForIdentifier.declarations.length === 0) {
+ return null;
+ }
+
+ const declarationNode = symbolForIdentifier.declarations[0];
+ if (!ts.isVariableDeclaration(declarationNode) || declarationNode.initializer === undefined ||
+ !ts.isObjectLiteralExpression(declarationNode.initializer)) {
+ return null;
+ }
+
+ return declarationNode.initializer;
+ }
+
+ private getLiteralNeedingMigration(node: ts.VariableDeclaration): ts.ObjectLiteralExpression
+ |null {
+ if (node.initializer === undefined) {
+ return null;
+ }
+
+ // declaration could be `x: ExtraOptions = {}` or `x = {} as ExtraOptions`
+ if (ts.isAsExpression(node.initializer) &&
+ ts.isObjectLiteralExpression(node.initializer.expression) &&
+ isExtraOptions(this.typeChecker, node.initializer.type)) {
+ return node.initializer.expression;
+ } else if (
+ node.type !== undefined && ts.isObjectLiteralExpression(node.initializer) &&
+ isExtraOptions(this.typeChecker, node.type)) {
+ return node.initializer;
+ }
+
+ return null;
+ }
+}
+
+/**
+ * Check whether the value assigned to an `initialNavigation` assignment
+ * conforms to the expected types for ExtraOptions#InitialNavigation
+ * @param node the property assignment to check
+ */
+function isValidInitialNavigationValue(node: ts.PropertyAssignment): boolean {
+ return ts.isStringLiteralLike(node.initializer) ||
+ node.initializer.kind === ts.SyntaxKind.FalseKeyword ||
+ node.initializer.kind === ts.SyntaxKind.TrueKeyword;
+}

packages/core/schematics/migrations/initial-navigation/google3/BUILD.bazel

@@ -0,0 +1,13 @@
+load("//tools:defaults.bzl", "ts_library")
+
+ts_library(
+ name = "google3",
+ srcs = glob(["**/*.ts"]),
+ tsconfig = "//packages/core/schematics:tsconfig.json",
+ visibility = ["//packages/core/schematics/migrations/google3:__pkg__"],
+ deps = [
+ "//packages/core/schematics/migrations/initial-navigation",
+ "@npm//tslint",
+ "@npm//typescript",
+ ],
+)

packages/core/schematics/migrations/initial-navigation/google3/tslint_update_recorder.ts

@@ -0,0 +1,26 @@
+/**
+ * @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 {Replacement, RuleFailure} from 'tslint';
+import * as ts from 'typescript';
+
+import {UpdateRecorder} from '../update_recorder';
+
+export class TslintUpdateRecorder implements UpdateRecorder {
+ failures: RuleFailure[] = [];
+
+ constructor(private ruleName: string, private sourceFile: ts.SourceFile) {}
+
+ updateNode(node: ts.Node, newText: string): void {
+ this.failures.push(new RuleFailure(
+ this.sourceFile, node.getStart(), node.getEnd(), `Node needs to be updated to: ${newText}`,
+ this.ruleName, Replacement.replaceFromTo(node.getStart(), node.getEnd(), newText)));
+ }
+
+ commitUpdate() {}
+}

packages/core/schematics/migrations/initial-navigation/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @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, Tree} from '@angular-devkit/schematics';
+import {relative} from 'path';
+import * as ts from 'typescript';
+import {getProjectTsConfigPaths} from '../../utils/project_tsconfig_paths';
+import {createMigrationProgram} from '../../utils/typescript/compiler_host';
+import {InitialNavigationCollector} from './collector';
+import {InitialNavigationTransform} from './transform';
+import {UpdateRecorder} from './update_recorder';
+
+/** Entry point for the v10 "initialNavigation RouterModule options" schematic. */
+export default function(): Rule {
+ return (tree: Tree) => {
+ const {buildPaths, testPaths} = getProjectTsConfigPaths(tree);
+ const basePath = process.cwd();
+
+ if (!buildPaths.length && !testPaths.length) {
+ throw new SchematicsException(
+ 'Could not find any tsconfig file. Cannot update the "initialNavigation" option for RouterModule');
+ }
+
+ for (const tsconfigPath of [...buildPaths, ...testPaths]) {
+ runInitialNavigationMigration(tree, tsconfigPath, basePath);
+ }
+ };
+}
+
+function runInitialNavigationMigration(tree: Tree, tsconfigPath: string, basePath: string) {
+ const {program} = createMigrationProgram(tree, tsconfigPath, basePath);
+ const typeChecker = program.getTypeChecker();
+ const initialNavigationCollector = new InitialNavigationCollector(typeChecker);
+ const sourceFiles = program.getSourceFiles().filter(
+ f => !f.isDeclarationFile && !program.isSourceFileFromExternalLibrary(f));
+
+ // Analyze source files by detecting all modules.
+ sourceFiles.forEach(sourceFile => initialNavigationCollector.visitNode(sourceFile));
+
+ const {assignments} = initialNavigationCollector;
+ const transformer = new InitialNavigationTransform(typeChecker, getUpdateRecorder);
+ const updateRecorders = new Map<ts.SourceFile, UpdateRecorder>();
+ transformer.migrateInitialNavigationAssignments(Array.from(assignments));
+
+ // Walk through each update recorder and commit the update. We need to commit the
+ // updates in batches per source file as there can be only one recorder per source
+ // file in order to avoid shift character offsets.
+ updateRecorders.forEach(recorder => recorder.commitUpdate());
+
+ /** Gets the update recorder for the specified source file. */
+ function getUpdateRecorder(sourceFile: ts.SourceFile): UpdateRecorder {
+ if (updateRecorders.has(sourceFile)) {
+ return updateRecorders.get(sourceFile)!;
+ }
+ const treeRecorder = tree.beginUpdate(relative(basePath, sourceFile.fileName));
+ const recorder: UpdateRecorder = {
+ updateNode(node: ts.Node, newText: string) {
+ treeRecorder.remove(node.getStart(), node.getWidth());
+ treeRecorder.insertRight(node.getStart(), newText);
+ },
+ commitUpdate() {
+ tree.commitUpdate(treeRecorder);
+ }
+ };
+ updateRecorders.set(sourceFile, recorder);
+ return recorder;
+ }
+}