@dugararchit/cdk 0.0.0-dugararchit

package/schematics/schematics/update-tool/index.ts

@@ -0,0 +1,191 @@
+/**
+ * @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 {ComponentResourceCollector} from './component-resource-collector';
+import {FileSystem, WorkspacePath} from './file-system';
+import {defaultLogger, UpdateLogger} from './logger';
+import {Migration, MigrationCtor, MigrationFailure} from './migration';
+import {TargetVersion} from './target-version';
+import {parseTsconfigFile} from './utils/parse-tsconfig';
+import {createFileSystemCompilerHost} from './utils/virtual-host';
+
+/**
+ * An update project that can be run against individual migrations. An update project
+ * accepts a TypeScript program and a context that is provided to all migrations. The
+ * context is usually not used by migrations, but in some cases migrations rely on
+ * specifics from the tool that performs the update (e.g. the Angular CLI). In those cases,
+ * the context can provide the necessary specifics to the migrations in a type-safe way.
+ */
+export class UpdateProject<Context> {
+  private readonly _typeChecker: ts.TypeChecker = this._program.getTypeChecker();
+
+  constructor(
+    /** Context provided to all migrations. */
+    private _context: Context,
+    /** TypeScript program using workspace paths. */
+    private _program: ts.Program,
+    /** File system used for reading, writing and editing files. */
+    private _fileSystem: FileSystem,
+    /**
+     * Set of analyzed files. Used for avoiding multiple migration runs if
+     * files overlap between targets.
+     */
+    private _analyzedFiles: Set<WorkspacePath> = new Set(),
+    /** Logger used for printing messages. */
+    private _logger: UpdateLogger = defaultLogger,
+  ) {}
+
+  /**
+   * Migrates the project to the specified target version.
+   * @param migrationTypes Migrations that should be run.
+   * @param target Version the project should be updated to.
+   * @param data Upgrade data that is passed to all migration rules.
+   * @param additionalStylesheetPaths Additional stylesheets that should be migrated, if not
+   *   referenced in an Angular component. This is helpful for global stylesheets in a project.
+   */
+  migrate<Data>(
+    migrationTypes: MigrationCtor<Data, Context>[],
+    target: TargetVersion,
+    data: Data,
+    additionalStylesheetPaths?: string[],
+  ): {hasFailures: boolean} {
+    // Create instances of the specified migrations.
+    const migrations = this._createMigrations(migrationTypes, target, data);
+    // Creates the component resource collector. The collector can visit arbitrary
+    // TypeScript nodes and will find Angular component resources. Resources include
+    // templates and stylesheets. It also captures inline stylesheets and templates.
+    const resourceCollector = new ComponentResourceCollector(this._typeChecker, this._fileSystem);
+    // Collect all of the TypeScript source files we want to migrate. We don't
+    // migrate type definition files, or source files from external libraries.
+    const sourceFiles = this._program
+      .getSourceFiles()
+      .filter(f => !f.isDeclarationFile && !this._program.isSourceFileFromExternalLibrary(f));
+
+    // Helper function that visits a given TypeScript node and collects all referenced
+    // component resources (i.e. stylesheets or templates). Additionally, the helper
+    // visits the node in each instantiated migration.
+    const visitNodeAndCollectResources = (node: ts.Node) => {
+      migrations.forEach(r => r.visitNode(node));
+      ts.forEachChild(node, visitNodeAndCollectResources);
+      resourceCollector.visitNode(node);
+    };
+
+    // Walk through all source file, if it has not been visited before, and
+    // visit found nodes while collecting potential resources.
+    sourceFiles.forEach(sourceFile => {
+      const resolvedPath = this._fileSystem.resolve(sourceFile.fileName);
+      // Do not visit source files which have been checked as part of a
+      // previously migrated TypeScript project.
+      if (!this._analyzedFiles.has(resolvedPath)) {
+        visitNodeAndCollectResources(sourceFile);
+        this._analyzedFiles.add(resolvedPath);
+      }
+    });
+
+    // Walk through all resolved templates and visit them in each instantiated
+    // migration. Note that this can only happen after source files have been
+    // visited because we find templates through the TypeScript source files.
+    resourceCollector.resolvedTemplates.forEach(template => {
+      // Do not visit the template if it has been checked before. Inline
+      // templates cannot be referenced multiple times.
+      if (template.inline || !this._analyzedFiles.has(template.filePath)) {
+        migrations.forEach(m => m.visitTemplate(template));
+        this._analyzedFiles.add(template.filePath);
+      }
+    });
+
+    // Walk through all resolved stylesheets and visit them in each instantiated
+    // migration. Note that this can only happen after source files have been
+    // visited because we find stylesheets through the TypeScript source files.
+    resourceCollector.resolvedStylesheets.forEach(stylesheet => {
+      // Do not visit the stylesheet if it has been checked before. Inline
+      // stylesheets cannot be referenced multiple times.
+      if (stylesheet.inline || !this._analyzedFiles.has(stylesheet.filePath)) {
+        migrations.forEach(r => r.visitStylesheet(stylesheet));
+        this._analyzedFiles.add(stylesheet.filePath);
+      }
+    });
+
+    // In some applications, developers will have global stylesheets which are not
+    // specified in any Angular component. Therefore we allow for additional stylesheets
+    // being specified. We visit them in each migration unless they have been already
+    // discovered before as actual component resource.
+    if (additionalStylesheetPaths) {
+      additionalStylesheetPaths.forEach(filePath => {
+        const resolvedPath = this._fileSystem.resolve(filePath);
+        const stylesheet = resourceCollector.resolveExternalStylesheet(resolvedPath, null);
+        // Do not visit stylesheets which have been referenced from a component.
+        if (!this._analyzedFiles.has(resolvedPath) && stylesheet) {
+          migrations.forEach(r => r.visitStylesheet(stylesheet));
+          this._analyzedFiles.add(resolvedPath);
+        }
+      });
+    }
+
+    // Call the "postAnalysis" method for each migration.
+    migrations.forEach(r => r.postAnalysis());
+
+    // Collect all failures reported by individual migrations.
+    const failures = migrations.reduce(
+      (res, m) => res.concat(m.failures),
+      [] as MigrationFailure[],
+    );
+
+    // In case there are failures, print these to the CLI logger as warnings.
+    if (failures.length) {
+      failures.forEach(({filePath, message, position}) => {
+        const lineAndCharacter = position ? `@${position.line + 1}:${position.character + 1}` : '';
+        this._logger.warn(`${filePath}${lineAndCharacter} - ${message}`);
+      });
+    }
+
+    return {
+      hasFailures: !!failures.length,
+    };
+  }
+
+  /**
+   * Creates instances of the given migrations with the specified target
+   * version and data.
+   */
+  private _createMigrations<Data>(
+    types: MigrationCtor<Data, Context>[],
+    target: TargetVersion,
+    data: Data,
+  ): Migration<Data, Context>[] {
+    const result: Migration<Data, Context>[] = [];
+    for (const ctor of types) {
+      const instance = new ctor(
+        this._program,
+        this._typeChecker,
+        target,
+        this._context,
+        data,
+        this._fileSystem,
+        this._logger,
+      );
+      instance.init();
+      if (instance.enabled) {
+        result.push(instance);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Creates a program form the specified tsconfig and patches the host
+   * to read files and directories through the given file system.
+   */
+  static createProgramFromTsconfig(tsconfigPath: WorkspacePath, fs: FileSystem): ts.Program {
+    const parsed = parseTsconfigFile(fs.resolve(tsconfigPath), fs);
+    const host = createFileSystemCompilerHost(parsed.options, fs);
+    return ts.createProgram(parsed.fileNames, parsed.options, host);
+  }
+}

package/schematics/schematics/update-tool/logger.ts

@@ -0,0 +1,23 @@
+/**
+ * @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
+ */
+
+export interface UpdateLogger {
+  debug(message: string): void;
+  error(message: string): void;
+  fatal(message: string): void;
+  info(message: string): void;
+  warn(message: string): void;
+}
+
+export const defaultLogger: UpdateLogger = {
+  debug: m => console.debug(m),
+  error: m => console.error(m),
+  fatal: m => console.error(m),
+  info: m => console.info(m),
+  warn: m => console.warn(m),
+};

package/schematics/schematics/update-tool/migration.ts

@@ -0,0 +1,88 @@
+/**
+ * @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 {ResolvedResource} from './component-resource-collector';
+import {FileSystem, WorkspacePath} from './file-system';
+import {UpdateLogger} from './logger';
+import {TargetVersion} from './target-version';
+import {LineAndCharacter} from './utils/line-mappings';
+
+export interface MigrationFailure {
+  filePath: WorkspacePath;
+  message: string;
+  position?: LineAndCharacter;
+}
+
+export type PostMigrationAction = void | {
+  /** Whether the package manager should run upon migration completion. */
+  runPackageManager: boolean;
+};
+
+/** Creates a constructor type for the specified type. */
+export type Constructor<T> = new (...args: any[]) => T;
+/** Gets a constructor type for the passed migration data. */
+export type MigrationCtor<Data, Context = any> = Constructor<Migration<Data, Context>>;
+
+export abstract class Migration<Data, Context = any> {
+  /** List of migration failures that need to be reported. */
+  failures: MigrationFailure[] = [];
+
+  /** Whether the migration is enabled or not. */
+  abstract enabled: boolean;
+
+  constructor(
+    /** TypeScript program for the migration. */
+    public program: ts.Program,
+    /** TypeChecker instance for the analysis program. */
+    public typeChecker: ts.TypeChecker,
+    /** Version for which the migration rule should run. */
+    public targetVersion: TargetVersion,
+    /** Context data for the migration. */
+    public context: Context,
+    /** Upgrade data passed to the migration. */
+    public upgradeData: Data,
+    /** File system that can be used for modifying files. */
+    public fileSystem: FileSystem,
+    /** Logger that can be used to print messages as part of the migration. */
+    public logger: UpdateLogger,
+  ) {}
+
+  /** Method can be used to perform global analysis of the program. */
+  init(): void {}
+
+  /**
+   * Method that will be called once all nodes, templates and stylesheets
+   * have been visited.
+   */
+  postAnalysis(): void {}
+
+  /**
+   * Method that will be called for each node in a given source file. Unlike tslint, this
+   * function will only retrieve TypeScript nodes that need to be casted manually. This
+   * allows us to only walk the program source files once per program and not per
+   * migration rule (significant performance boost).
+   */
+  visitNode(node: ts.Node): void {}
+
+  /** Method that will be called for each Angular template in the program. */
+  visitTemplate(template: ResolvedResource): void {}
+
+  /** Method that will be called for each stylesheet in the program. */
+  visitStylesheet(stylesheet: ResolvedResource): void {}
+
+  /** Creates a failure with a specified message at the given node location. */
+  protected createFailureAtNode(node: ts.Node, message: string) {
+    const sourceFile = node.getSourceFile();
+    this.failures.push({
+      filePath: this.fileSystem.resolve(sourceFile.fileName),
+      position: ts.getLineAndCharacterOfPosition(sourceFile, node.getStart()),
+      message: message,
+    });
+  }
+}

package/schematics/schematics/update-tool/public-api.ts

@@ -0,0 +1,16 @@
+/**
+ * @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
+ */
+
+export * from './component-resource-collector';
+export * from './file-system';
+export * from './index';
+export * from './migration';
+export * from './target-version';
+export * from './utils/decorators';
+export * from './utils/imports';
+export * from './version-changes';

package/schematics/schematics/update-tool/target-version.ts

@@ -0,0 +1,31 @@
+/**
+ * @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
+ */
+
+/** Possible versions that can be automatically migrated by `ng update`. */
+// Used in an `Object.keys` call below so it can't be `const enum`.
+// tslint:disable-next-line:prefer-const-enum
+export enum TargetVersion {
+  V6 = 'version 6',
+  V7 = 'version 7',
+  V8 = 'version 8',
+  V9 = 'version 9',
+  V10 = 'version 10',
+  V11 = 'version 11',
+  V12 = 'version 12',
+  V13 = 'version 13',
+}
+
+/**
+ * Returns all versions that are supported by "ng update". The versions are determined
+ * based on the "TargetVersion" enum.
+ */
+export function getAllVersionNames(): string[] {
+  return Object.keys(TargetVersion).filter(enumValue => {
+    return typeof (TargetVersion as Record<string, string | undefined>)[enumValue] === 'string';
+  });
+}

package/schematics/schematics/update-tool/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "lib": ["es2015"],
+    "types": ["node", "glob"]
+  }
+}

package/schematics/schematics/update-tool/update-recorder.ts

@@ -0,0 +1,14 @@
+/**
+ * @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
+ */
+
+/** Update recorder that can be used to apply changes to a source file. */
+export interface UpdateRecorder {
+  insertLeft(index: number, content: string): UpdateRecorder;
+  insertRight(index: number, content: string): UpdateRecorder;
+  remove(index: number, length: number): UpdateRecorder;
+}

package/schematics/schematics/update-tool/utils/decorators.ts

@@ -0,0 +1,54 @@
+/**
+ * @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 {getImportOfIdentifier, Import} from './imports';
+
+export type CallExpressionDecorator = ts.Decorator & {
+  expression: ts.CallExpression;
+};
+
+export interface NgDecorator {
+  name: string;
+  node: CallExpressionDecorator;
+}
+
+/**
+ * Gets all decorators which are imported from an Angular package
+ * (e.g. "@angular/core") from a list of decorators.
+ */
+export function getAngularDecorators(
+  typeChecker: ts.TypeChecker,
+  decorators: readonly ts.Decorator[],
+): readonly NgDecorator[] {
+  return decorators
+    .map(node => ({node, importData: getCallDecoratorImport(typeChecker, node)}))
+    .filter(({importData}) => importData && importData.moduleName.startsWith('@angular/'))
+    .map(({node, importData}) => ({
+      node: node as CallExpressionDecorator,
+      name: importData!.symbolName,
+    }));
+}
+
+export function getCallDecoratorImport(
+  typeChecker: ts.TypeChecker,
+  decorator: ts.Decorator,
+): Import | null {
+  if (!ts.isCallExpression(decorator.expression)) {
+    return null;
+  }
+  const valueExpr = decorator.expression.expression;
+  let identifier: ts.Identifier | null = null;
+  if (ts.isIdentifier(valueExpr)) {
+    identifier = valueExpr;
+  } else if (ts.isPropertyAccessExpression(valueExpr) && ts.isIdentifier(valueExpr.name)) {
+    identifier = valueExpr.name;
+  }
+  return identifier ? getImportOfIdentifier(identifier, typeChecker) : null;
+}

package/schematics/schematics/update-tool/utils/functions.ts

@@ -0,0 +1,18 @@
+/**
+ * @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';
+
+/**
+ * Unwraps a given expression TypeScript node. Expressions can be wrapped within multiple
+ * parentheses. e.g. "(((({exp}))))()". The function should return the TypeScript node
+ * referring to the inner expression. e.g "exp".
+ */
+export function unwrapExpression(node: ts.Expression | ts.ParenthesizedExpression): ts.Expression {
+  return ts.isParenthesizedExpression(node) ? unwrapExpression(node.expression) : node;
+}

package/schematics/schematics/update-tool/utils/imports.ts

@@ -0,0 +1,128 @@
+/**
+ * @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';
+
+/** Interface describing a resolved import. */
+export interface Import {
+  /** Name of the imported symbol. */
+  symbolName: string;
+  /** Module name from which the symbol has been imported. */
+  moduleName: string;
+}
+
+/** Resolves the import of the specified identifier. */
+export function getImportOfIdentifier(
+  node: ts.Identifier,
+  typeChecker: ts.TypeChecker,
+): Import | null {
+  // Free standing identifiers which resolve to an import will be handled
+  // as direct imports. e.g. "@Component()" where "Component" is an identifier
+  // referring to an import specifier.
+  const directImport = getSpecificImportOfIdentifier(node, typeChecker);
+  if (directImport !== null) {
+    return directImport;
+  } else if (ts.isQualifiedName(node.parent) && node.parent.right === node) {
+    // Determines the import of a qualified name. e.g. "let t: core.Component". In that
+    // case, the import of the most left identifier will be determined ("core").
+    const qualifierRoot = getQualifiedNameRoot(node.parent);
+    if (qualifierRoot) {
+      const moduleName = getImportOfNamespacedIdentifier(qualifierRoot, typeChecker);
+      if (moduleName) {
+        return {moduleName, symbolName: node.text};
+      }
+    }
+  } else if (ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) {
+    // Determines the import of a property expression. e.g. "@core.Component". In that
+    // case, the import of the most left identifier will be determined ("core").
+    const rootIdentifier = getPropertyAccessRoot(node.parent);
+    if (rootIdentifier) {
+      const moduleName = getImportOfNamespacedIdentifier(rootIdentifier, typeChecker);
+      if (moduleName) {
+        return {moduleName, symbolName: node.text};
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolves the import of the specified identifier. Expects the identifier to resolve
+ * to a fine-grained import declaration with import specifiers.
+ */
+function getSpecificImportOfIdentifier(
+  node: ts.Identifier,
+  typeChecker: ts.TypeChecker,
+): Import | null {
+  const symbol = typeChecker.getSymbolAtLocation(node);
+  if (!symbol || !symbol.declarations || !symbol.declarations.length) {
+    return null;
+  }
+  const declaration = symbol.declarations[0];
+  if (!ts.isImportSpecifier(declaration)) {
+    return null;
+  }
+  // Since the declaration is an import specifier, we can walk up three times to get a reference
+  // to the import declaration node (NamedImports -> ImportClause -> ImportDeclaration).
+  const importDecl = declaration.parent.parent.parent;
+  if (!ts.isStringLiteral(importDecl.moduleSpecifier)) {
+    return null;
+  }
+  return {
+    moduleName: importDecl.moduleSpecifier.text,
+    symbolName: declaration.propertyName ? declaration.propertyName.text : declaration.name.text,
+  };
+}
+
+/**
+ * Resolves the import of the specified identifier. Expects the identifier to
+ * resolve to a namespaced import declaration. e.g. "import * as core from ...".
+ */
+function getImportOfNamespacedIdentifier(
+  node: ts.Identifier,
+  typeChecker: ts.TypeChecker,
+): string | null {
+  const symbol = typeChecker.getSymbolAtLocation(node);
+  if (!symbol || !symbol.declarations || !symbol.declarations.length) {
+    return null;
+  }
+  const declaration = symbol.declarations[0];
+  if (!ts.isNamespaceImport(declaration)) {
+    return null;
+  }
+  // Since the declaration is a namespace import, we can walk up three times to get a reference
+  // to the import declaration node (NamespaceImport -> ImportClause -> ImportDeclaration).
+  const importDecl = declaration.parent.parent;
+  if (!ts.isStringLiteral(importDecl.moduleSpecifier)) {
+    return null;
+  }
+
+  return importDecl.moduleSpecifier.text;
+}
+
+/**
+ * Gets the root identifier of a qualified type chain. For example: "core.GestureConfig"
+ * will return the "core" identifier. Allowing us to find the import of "core".
+ */
+function getQualifiedNameRoot(name: ts.QualifiedName): ts.Identifier | null {
+  while (ts.isQualifiedName(name.left)) {
+    name = name.left;
+  }
+  return ts.isIdentifier(name.left) ? name.left : null;
+}
+
+/**
+ * Gets the root identifier of a property access chain. For example: "core.GestureConfig"
+ * will return the "core" identifier. Allowing us to find the import of "core".
+ */
+function getPropertyAccessRoot(node: ts.PropertyAccessExpression): ts.Identifier | null {
+  while (ts.isPropertyAccessExpression(node.expression)) {
+    node = node.expression;
+  }
+  return ts.isIdentifier(node.expression) ? node.expression : null;
+}

package/schematics/schematics/update-tool/utils/line-mappings.ts

@@ -0,0 +1,84 @@
+/**
+ * @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
+ */
+
+/*
+ * Line mapping utilities which can be used to retrieve line and character based
+ * on an absolute character position in a given file. This functionality is similar
+ * to TypeScript's "ts.getLineAndCharacterFromPosition" utility, but we cannot leverage
+ * their logic for line mappings as it's internal and we need to generate line mappings
+ * for non-TypeScript files such as HTML templates or stylesheets.
+ *
+ * Line and character can be retrieved by splitting a given source text based on
+ * line breaks into line start entries. Later when a specific position is requested,
+ * the closest line-start position is determined based on the given position.
+ */
+
+const LF_CHAR = 10;
+const CR_CHAR = 13;
+const LINE_SEP_CHAR = 8232;
+const PARAGRAPH_CHAR = 8233;
+
+export interface LineAndCharacter {
+  character: number;
+  line: number;
+}
+
+/** Gets the line and character for the given position from the line starts map. */
+export function getLineAndCharacterFromPosition(lineStartsMap: number[], position: number) {
+  const lineIndex = findClosestLineStartPosition(lineStartsMap, position);
+  return {character: position - lineStartsMap[lineIndex], line: lineIndex};
+}
+
+/**
+ * Computes the line start map of the given text. This can be used in order to
+ * retrieve the line and character of a given text position index.
+ */
+export function computeLineStartsMap(text: string): number[] {
+  const result: number[] = [0];
+  let pos = 0;
+  while (pos < text.length) {
+    const char = text.charCodeAt(pos++);
+    // Handles the "CRLF" line break. In that case we peek the character
+    // after the "CR" and check if it is a line feed.
+    if (char === CR_CHAR) {
+      if (text.charCodeAt(pos) === LF_CHAR) {
+        pos++;
+      }
+      result.push(pos);
+    } else if (char === LF_CHAR || char === LINE_SEP_CHAR || char === PARAGRAPH_CHAR) {
+      result.push(pos);
+    }
+  }
+  result.push(pos);
+  return result;
+}
+
+/** Finds the closest line start for the given position. */
+function findClosestLineStartPosition<T>(
+  linesMap: T[],
+  position: T,
+  low = 0,
+  high = linesMap.length - 1,
+) {
+  while (low <= high) {
+    const pivotIndex = Math.floor((low + high) / 2);
+    const pivotEl = linesMap[pivotIndex];
+
+    if (pivotEl === position) {
+      return pivotIndex;
+    } else if (position > pivotEl) {
+      low = pivotIndex + 1;
+    } else {
+      high = pivotIndex - 1;
+    }
+  }
+
+  // In case there was no exact match, return the closest "lower" line index. We also
+  // subtract the index by one because want the index of the previous line start.
+  return low - 1;
+}