@angular-devkit/schematics 14.0.0-next.7 → 14.0.0-rc.0

package/README.md

@@ -23,7 +23,7 @@ What distinguishes Schematics from other generators, such as Yeoman or Yarn Crea
 
 # Tooling
 
-Schematics is a library, and does not work by itself. A [reference CLI](https://github.com/angular/angular-cli/blob/master/packages/angular_devkit/schematics_cli/bin/schematics.ts) is available on this repository, and is published on NPM at [@angular-devkit/schematics-cli](https://www.npmjs.com/package/@angular-devkit/schematics-cli). This document explains the library usage and the tooling API, but does not go into the tool implementation itself.
+Schematics is a library, and does not work by itself. A [reference CLI](https://github.com/angular/angular-cli/blob/main/packages/angular_devkit/schematics_cli/bin/schematics.ts) is available on this repository, and is published on NPM at [@angular-devkit/schematics-cli](https://www.npmjs.com/package/@angular-devkit/schematics-cli). This document explains the library usage and the tooling API, but does not go into the tool implementation itself.
 
 The tooling is responsible for the following tasks:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-devkit/schematics",
-  "version": "14.0.0-next.7",
+  "version": "14.0.0-rc.0",
   "description": "Angular Schematics - Library",
   "main": "src/index.js",
   "typings": "src/index.d.ts",
@@ -18,7 +18,7 @@
     "schematics"
   ],
   "dependencies": {
-    "@angular-devkit/core": "14.0.0-next.7",
+    "@angular-devkit/core": "14.0.0-rc.0",
     "jsonc-parser": "3.0.0",
     "magic-string": "0.26.1",
     "ora": "5.4.1",

package/src/engine/engine.d.ts

@@ -54,7 +54,7 @@ export declare class TaskScheduler {
     constructor(_context: SchematicContext);
     private _calculatePriority;
     private _mapDependencies;
-    schedule<T>(taskConfiguration: TaskConfiguration<T>): TaskId;
+    schedule<T extends object>(taskConfiguration: TaskConfiguration<T>): TaskId;
     finalize(): ReadonlyArray<TaskInfo>;
 }
 export declare class SchematicEngine<CollectionT extends object, SchematicT extends object> implements Engine<CollectionT, SchematicT> {

package/src/engine/interface.d.ts

@@ -124,7 +124,7 @@ export interface TypedSchematicContext<CollectionMetadataT extends object, Schem
     readonly schematic: Schematic<CollectionMetadataT, SchematicMetadataT>;
     readonly strategy: MergeStrategy;
     readonly interactive: boolean;
-    addTask<T>(task: TaskConfigurationGenerator<T>, dependencies?: Array<TaskId>): TaskId;
+    addTask<T extends object>(task: TaskConfigurationGenerator<T>, dependencies?: Array<TaskId>): TaskId;
 }
 /**
  * This is used by the Schematics implementations in order to avoid needing to have typing from

package/src/index.d.ts

@@ -5,6 +5,7 @@
  * 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 { strings } from '@angular-devkit/core';
 import * as formats from './formats/index';
 import { FilePredicate, MergeStrategy, Tree as TreeInterface } from './tree/interface';
 import * as workflow from './workflow/index';
@@ -28,8 +29,7 @@ export * from './engine/schematic';
 export * from './sink/dryrun';
 export * from './sink/host';
 export * from './sink/sink';
-export { formats };
-export { workflow };
+export { formats, strings, workflow };
 export interface TreeConstructor {
     empty(): TreeInterface;
     branch(tree: TreeInterface): TreeInterface;

package/src/index.js

@@ -33,7 +33,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Tree = exports.workflow = exports.formats = exports.SchematicsException = void 0;
+exports.Tree = exports.workflow = exports.strings = exports.formats = exports.SchematicsException = void 0;
+const core_1 = require("@angular-devkit/core");
+Object.defineProperty(exports, "strings", { enumerable: true, get: function () { return core_1.strings; } });
 const formats = __importStar(require("./formats/index"));
 exports.formats = formats;
 const interface_1 = require("./tree/interface");

package/src/rules/template.d.ts

@@ -35,5 +35,5 @@ export declare function pathTemplate<T extends PathTemplateData>(options: T): Ru
  * Remove every `.template` suffix from file names.
  */
 export declare function renameTemplateFiles(): Rule;
-export declare function template<T>(options: T): Rule;
-export declare function applyTemplates<T>(options: T): Rule;
+export declare function template<T extends object>(options: T): Rule;
+export declare function applyTemplates<T extends object>(options: T): Rule;

package/src/tree/delegate.d.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 /// <reference types="node" />
+import { JsonValue } from '@angular-devkit/core';
 import { Action } from './action';
 import { DirEntry, FileEntry, FileVisitor, MergeStrategy, Tree, UpdateRecorder } from './interface';
 export declare class DelegateTree implements Tree {
@@ -15,6 +16,8 @@ export declare class DelegateTree implements Tree {
     merge(other: Tree, strategy?: MergeStrategy): void;
     get root(): DirEntry;
     read(path: string): Buffer | null;
+    readText(path: string): string;
+    readJson(path: string): JsonValue;
     exists(path: string): boolean;
     get(path: string): FileEntry | null;
     getDir(path: string): DirEntry;

package/src/tree/delegate.js

@@ -26,6 +26,12 @@ class DelegateTree {
     read(path) {
         return this._other.read(path);
     }
+    readText(path) {
+        return this._other.readText(path);
+    }
+    readJson(path) {
+        return this._other.readJson(path);
+    }
     exists(path) {
         return this._other.exists(path);
     }

package/src/tree/host-tree.d.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 /// <reference types="node" />
-import { Path, PathFragment, virtualFs } from '@angular-devkit/core';
+import { JsonValue, Path, PathFragment, virtualFs } from '@angular-devkit/core';
 import { Action } from './action';
 import { DirEntry, FileEntry, FilePredicate, FileVisitor, MergeStrategy, Tree, UpdateRecorder } from './interface';
 export declare class HostDirEntry implements DirEntry {
@@ -41,6 +41,8 @@ export declare class HostTree implements Tree {
     merge(other: Tree, strategy?: MergeStrategy): void;
     get root(): DirEntry;
     read(path: string): Buffer | null;
+    readText(path: string): string;
+    readJson(path: string): JsonValue;
     exists(path: string): boolean;
     get(path: string): FileEntry | null;
     getDir(path: string): DirEntry;

package/src/tree/host-tree.js

@@ -9,8 +9,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FilterHostTree = exports.HostCreateTree = exports.HostTree = exports.HostDirEntry = void 0;
 const core_1 = require("@angular-devkit/core");
+const jsonc_parser_1 = require("jsonc-parser");
 const rxjs_1 = require("rxjs");
 const operators_1 = require("rxjs/operators");
+const util_1 = require("util");
 const exception_1 = require("../exception/exception");
 const delegate_1 = require("./delegate");
 const entry_1 = require("./entry");
@@ -208,6 +210,34 @@ class HostTree {
         const entry = this.get(path);
         return entry ? entry.content : null;
     }
+    readText(path) {
+        const data = this.read(path);
+        if (data === null) {
+            throw new exception_1.FileDoesNotExistException(path);
+        }
+        const decoder = new util_1.TextDecoder('utf-8', { fatal: true });
+        try {
+            // With the `fatal` option enabled, invalid data will throw a TypeError
+            return decoder.decode(data);
+        }
+        catch (e) {
+            if (e instanceof TypeError) {
+                throw new Error(`Failed to decode "${path}" as UTF-8 text.`);
+            }
+            throw e;
+        }
+    }
+    readJson(path) {
+        const content = this.readText(path);
+        const errors = [];
+        const result = (0, jsonc_parser_1.parse)(content, errors, { allowTrailingComma: true });
+        // If there is a parse error throw with the error information
+        if (errors[0]) {
+            const { error, offset } = errors[0];
+            throw new Error(`Failed to parse "${path}" as JSON. ${(0, jsonc_parser_1.printParseErrorCode)(error)} at offset: ${offset}.`);
+        }
+        return result;
+    }
     exists(path) {
         return this._recordSync.isFile(this._normalizePath(path));
     }

package/src/tree/interface.d.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 /// <reference types="node" />
-import { Path, PathFragment } from '@angular-devkit/core';
+import { JsonValue, Path, PathFragment } from '@angular-devkit/core';
 import { Action } from './action';
 export declare enum MergeStrategy {
     AllowOverwriteConflict = 2,
@@ -41,6 +41,28 @@ export interface Tree {
     merge(other: Tree, strategy?: MergeStrategy): void;
     readonly root: DirEntry;
     read(path: string): Buffer | null;
+    /**
+     * Reads a file from the Tree as a UTF-8 encoded text file.
+     *
+     * @param path The path of the file to read.
+     * @returns A string containing the contents of the file.
+     * @throws {@link FileDoesNotExistException} if the file is not found.
+     * @throws An error if the file contains invalid UTF-8 characters.
+     */
+    readText(path: string): string;
+    /**
+     * Reads and parses a file from the Tree as a UTF-8 encoded JSON file.
+     * Supports parsing JSON (RFC 8259) with the following extensions:
+     * * Single-line and multi-line JavaScript comments
+     * * Trailing commas within objects and arrays
+     *
+     * @param path The path of the file to read.
+     * @returns A JsonValue containing the parsed contents of the file.
+     * @throws {@link FileDoesNotExistException} if the file is not found.
+     * @throws An error if the file contains invalid UTF-8 characters.
+     * @throws An error if the file contains malformed JSON.
+     */
+    readJson(path: string): JsonValue;
     exists(path: string): boolean;
     get(path: string): FileEntry | null;
     getDir(path: string): DirEntry;

package/src/tree/null.d.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 /// <reference types="node" />
-import { BaseException, Path, PathFragment } from '@angular-devkit/core';
+import { BaseException, JsonValue, Path, PathFragment } from '@angular-devkit/core';
 import { Action } from './action';
 import { DirEntry, MergeStrategy, Tree, UpdateRecorder } from './interface';
 export declare class CannotCreateFileException extends BaseException {
@@ -28,6 +28,8 @@ export declare class NullTree implements Tree {
     readonly root: DirEntry;
     exists(_path: string): boolean;
     read(_path: string): null;
+    readText(path: string): string;
+    readJson(path: string): JsonValue;
     get(_path: string): null;
     getDir(path: string): NullTreeDirEntry;
     visit(): void;

package/src/tree/null.js

@@ -54,6 +54,12 @@ class NullTree {
     read(_path) {
         return null;
     }
+    readText(path) {
+        throw new exception_1.FileDoesNotExistException(path);
+    }
+    readJson(path) {
+        throw new exception_1.FileDoesNotExistException(path);
+    }
     get(_path) {
         return null;
     }

package/src/tree/scoped.d.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 /// <reference types="node" />
-import { Path, PathFragment } from '@angular-devkit/core';
+import { JsonValue, Path, PathFragment } from '@angular-devkit/core';
 import { Action } from './action';
 import { DirEntry, FileEntry, FileVisitor, MergeStrategy, Tree, UpdateRecorder } from './interface';
 declare class ScopedDirEntry implements DirEntry {
@@ -29,6 +29,8 @@ export declare class ScopedTree implements Tree {
     branch(): Tree;
     merge(other: Tree, strategy?: MergeStrategy): void;
     read(path: string): Buffer | null;
+    readText(path: string): string;
+    readJson(path: string): JsonValue;
     exists(path: string): boolean;
     get(path: string): FileEntry | null;
     getDir(path: string): DirEntry;

package/src/tree/scoped.js

@@ -83,6 +83,12 @@ class ScopedTree {
     read(path) {
         return this._base.read(this._fullPath(path));
     }
+    readText(path) {
+        return this._base.readText(this._fullPath(path));
+    }
+    readJson(path) {
+        return this._base.readJson(this._fullPath(path));
+    }
     exists(path) {
         return this._base.exists(this._fullPath(path));
     }

package/tasks/package-manager/executor.js

@@ -110,6 +110,9 @@ function default_1(factoryOptions = {}) {
         if (options.quiet && taskPackageManagerProfile.quietArgument) {
             args.push(taskPackageManagerProfile.quietArgument);
         }
+        if (!options.allowScripts) {
+            args.push('--ignore-scripts');
+        }
         if (factoryOptions.registry) {
             args.push(`--registry="${factoryOptions.registry}"`);
         }

package/tasks/package-manager/install-task.d.ts

@@ -13,10 +13,12 @@ interface NodePackageInstallTaskOptions {
     workingDirectory?: string;
     quiet?: boolean;
     hideOutput?: boolean;
+    allowScripts?: boolean;
 }
 export declare class NodePackageInstallTask implements TaskConfigurationGenerator<NodePackageTaskOptions> {
     quiet: boolean;
     hideOutput: boolean;
+    allowScripts: boolean;
     workingDirectory?: string;
     packageManager?: string;
     packageName?: string;

package/tasks/package-manager/install-task.js

@@ -13,6 +13,7 @@ class NodePackageInstallTask {
     constructor(options) {
         this.quiet = true;
         this.hideOutput = true;
+        this.allowScripts = false;
         if (typeof options === 'string') {
             this.workingDirectory = options;
         }
@@ -32,6 +33,9 @@ class NodePackageInstallTask {
             if (options.packageName != undefined) {
                 this.packageName = options.packageName;
             }
+            if (options.allowScripts !== undefined) {
+                this.allowScripts = options.allowScripts;
+            }
         }
     }
     toConfiguration() {
@@ -44,6 +48,7 @@ class NodePackageInstallTask {
                 workingDirectory: this.workingDirectory,
                 packageManager: this.packageManager,
                 packageName: this.packageName,
+                allowScripts: this.allowScripts,
             },
         };
     }

package/tasks/package-manager/options.d.ts

@@ -20,4 +20,5 @@ export interface NodePackageTaskOptions {
     workingDirectory?: string;
     packageName?: string;
     packageManager?: string;
+    allowScripts?: boolean;
 }

package/testing/schematic-test-runner.d.ts

@@ -23,7 +23,7 @@ export declare class SchematicTestRunner {
     get logger(): logging.Logger;
     get tasks(): TaskConfiguration[];
     registerCollection(collectionName: string, collectionPath: string): void;
-    runSchematicAsync<SchematicSchemaT>(schematicName: string, opts?: SchematicSchemaT, tree?: Tree): Observable<UnitTestTree>;
-    runExternalSchematicAsync<SchematicSchemaT>(collectionName: string, schematicName: string, opts?: SchematicSchemaT, tree?: Tree): Observable<UnitTestTree>;
+    runSchematicAsync<SchematicSchemaT extends object>(schematicName: string, opts?: SchematicSchemaT, tree?: Tree): Observable<UnitTestTree>;
+    runExternalSchematicAsync<SchematicSchemaT extends object>(collectionName: string, schematicName: string, opts?: SchematicSchemaT, tree?: Tree): Observable<UnitTestTree>;
     callRule(rule: Rule, tree: Tree, parentContext?: Partial<SchematicContext>): Observable<Tree>;
 }

package/tools/description.d.ts

@@ -14,6 +14,7 @@ export interface FileSystemCollectionDescription {
     readonly schematics: {
         [name: string]: FileSystemSchematicDesc;
     };
+    readonly encapsulation?: boolean;
 }
 export interface FileSystemSchematicJsonDescription {
     readonly aliases?: string[];

package/tools/file-system-engine-host-base.d.ts

@@ -11,7 +11,7 @@ import { Observable } from 'rxjs';
 import { Url } from 'url';
 import { RuleFactory, Source, TaskExecutor, TaskExecutorFactory } from '../src';
 import { FileSystemCollectionDesc, FileSystemEngineHost, FileSystemSchematicContext, FileSystemSchematicDesc, FileSystemSchematicDescription } from './description';
-export declare type OptionTransform<T extends object, R extends object> = (schematic: FileSystemSchematicDescription, options: T, context?: FileSystemSchematicContext) => Observable<R> | PromiseLike<R> | R;
+export declare type OptionTransform<T extends object | null, R extends object> = (schematic: FileSystemSchematicDescription, options: T, context?: FileSystemSchematicContext) => Observable<R> | PromiseLike<R> | R;
 export declare type ContextTransform = (context: FileSystemSchematicContext) => FileSystemSchematicContext;
 export declare class CollectionCannotBeResolvedException extends BaseException {
     constructor(name: string);
@@ -46,7 +46,7 @@ export declare class SchematicNameCollisionException extends BaseException {
  */
 export declare abstract class FileSystemEngineHostBase implements FileSystemEngineHost {
     protected abstract _resolveCollectionPath(name: string, requester?: string): string;
-    protected abstract _resolveReferenceString(name: string, parentPath: string): {
+    protected abstract _resolveReferenceString(name: string, parentPath: string, collectionDescription: FileSystemCollectionDesc): {
         ref: RuleFactory<{}>;
         path: string;
     } | null;
@@ -56,7 +56,7 @@ export declare abstract class FileSystemEngineHostBase implements FileSystemEngi
     private _contextTransforms;
     private _taskFactories;
     listSchematicNames(collection: FileSystemCollectionDesc, includeHidden?: boolean): string[];
-    registerOptionsTransform<T extends object, R extends object>(t: OptionTransform<T, R>): void;
+    registerOptionsTransform<T extends object | null, R extends object>(t: OptionTransform<T, R>): void;
     registerContextTransform(t: ContextTransform): void;
     /**
      *

package/tools/file-system-engine-host-base.js

@@ -178,7 +178,7 @@ class FileSystemEngineHostBase {
         if (!partialDesc.factory) {
             throw new SchematicMissingFactoryException(name);
         }
-        const resolvedRef = this._resolveReferenceString(partialDesc.factory, collectionPath);
+        const resolvedRef = this._resolveReferenceString(partialDesc.factory, collectionPath, collection);
         if (!resolvedRef) {
             throw new FactoryCannotBeResolvedException(name);
         }

package/tools/node-module-engine-host.d.ts

@@ -20,7 +20,7 @@ export declare class NodeModulesEngineHost extends FileSystemEngineHostBase {
     constructor(paths?: string[] | undefined);
     private resolve;
     protected _resolveCollectionPath(name: string, requester?: string): string;
-    protected _resolveReferenceString(refString: string, parentPath: string): {
+    protected _resolveReferenceString(refString: string, parentPath: string, collectionDescription?: FileSystemCollectionDesc): {
         ref: RuleFactory<{}>;
         path: string;
     } | null;

package/tools/node-module-engine-host.js

@@ -81,7 +81,7 @@ class NodeModulesEngineHost extends file_system_engine_host_base_1.FileSystemEng
         (0, file_system_utility_1.readJsonFile)(collectionPath);
         return collectionPath;
     }
-    _resolveReferenceString(refString, parentPath) {
+    _resolveReferenceString(refString, parentPath, collectionDescription) {
         const ref = new export_ref_1.ExportStringRef(refString, parentPath);
         if (!ref.ref) {
             return null;

package/tools/schema-option-transform.d.ts

@@ -11,4 +11,4 @@ import { FileSystemSchematicContext, FileSystemSchematicDescription } from './de
 export declare class InvalidInputOptions<T = {}> extends schema.SchemaValidationException {
     constructor(options: T, errors: schema.SchemaValidatorError[]);
 }
-export declare function validateOptionsWithSchema(registry: schema.SchemaRegistry): <T extends {}>(schematic: FileSystemSchematicDescription, options: T, context?: FileSystemSchematicContext | undefined) => Observable<T>;
+export declare function validateOptionsWithSchema(registry: schema.SchemaRegistry): <T extends {} | null>(schematic: FileSystemSchematicDescription, options: T, context?: FileSystemSchematicContext | undefined) => Observable<T>;

package/tools/workflow/node-workflow.d.ts

@@ -19,7 +19,7 @@ export interface NodeWorkflowOptions {
     registry?: schema.CoreSchemaRegistry;
     resolvePaths?: string[];
     schemaValidation?: boolean;
-    optionTransforms?: OptionTransform<object, object>[];
+    optionTransforms?: OptionTransform<Record<string, unknown> | null, object>[];
     engineHostCreator?: (options: NodeWorkflowOptions) => NodeModulesEngineHost;
 }
 /**