feat(@angular-devkit/schematics): support collection extension

packages/angular_devkit/schematics/collection-schema.json

@@ -4,6 +4,22 @@
   "title": "Collection Schema for validating a 'collection.json'.",
   "type": "object",
   "properties": {
+    "extends": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        }
+      ]
+    },
     "schematics": {
       "type": "object",
       "description": "A map of schematic names to schematic details",

packages/angular_devkit/schematics/src/engine/collection.ts

@@ -12,7 +12,8 @@ import { Collection, CollectionDescription, Schematic } from './interface';
 export class CollectionImpl<CollectionT extends object, SchematicT extends object>
     implements Collection<CollectionT, SchematicT> {
   constructor(private _description: CollectionDescription<CollectionT>,
-              private _engine: SchematicEngine<CollectionT, SchematicT>) {
+              private _engine: SchematicEngine<CollectionT, SchematicT>,
+              public readonly baseDescriptions?: Array<CollectionDescription<CollectionT>>) {
   }
 
   get description() { return this._description; }

packages/angular_devkit/schematics/src/engine/engine.ts

@@ -40,6 +40,13 @@ export class UnknownUrlSourceProtocol extends BaseException {
 export class UnknownCollectionException extends BaseException {
   constructor(name: string) { super(`Unknown collection "${name}".`); }
 }
+
+export class CircularCollectionException extends BaseException {
+  constructor(name: string) {
+    super(`Circular collection reference "${name}".`);
+  }
+}
+
 export class UnknownSchematicException extends BaseException {
   constructor(name: string, collection: CollectionDescription<{}>) {
     super(`Schematic "${name}" not found in collection "${collection.name}".`);
@@ -76,16 +83,38 @@ export class SchematicEngine<CollectionT extends object, SchematicT extends obje
       return collection;
     }
 
+    const [description, bases] = this._createCollectionDescription(name);
+
+    collection = new CollectionImpl<CollectionT, SchematicT>(description, this, bases);
+    this._collectionCache.set(name, collection);
+    this._schematicCache.set(name, new Map());
+
+    return collection;
+  }
+
+  private _createCollectionDescription(
+    name: string,
+    parentNames?: Set<string>,
+  ): [CollectionDescription<CollectionT>, Array<CollectionDescription<CollectionT>>] {
     const description = this._host.createCollectionDescription(name);
     if (!description) {
       throw new UnknownCollectionException(name);
     }
+    if (parentNames && parentNames.has(description.name)) {
+      throw new CircularCollectionException(name);
+    }
 
-    collection = new CollectionImpl<CollectionT, SchematicT>(description, this);
-    this._collectionCache.set(name, collection);
-    this._schematicCache.set(name, new Map());
+    const bases = new Array<CollectionDescription<CollectionT>>();
+    if (description.extends) {
+      parentNames = (parentNames || new Set<string>()).add(description.name);
+      for (const baseName of description.extends) {
+        const [base, baseBases] = this._createCollectionDescription(baseName, new Set(parentNames));
 
-    return collection;
+        bases.unshift(base, ...baseBases);
+      }
+    }
+
+    return [description, bases];
   }
 
   createContext(
@@ -148,21 +177,43 @@ export class SchematicEngine<CollectionT extends object, SchematicT extends obje
       return schematic;
     }
 
-    const description = this._host.createSchematicDescription(name, collection.description);
+    let collectionDescription = collection.description;
+    let description = this._host.createSchematicDescription(name, collection.description);
     if (!description) {
-      throw new UnknownSchematicException(name, collection.description);
+      if (collection.baseDescriptions) {
+        for (const base of collection.baseDescriptions) {
+          description = this._host.createSchematicDescription(name, base);
+          if (description) {
+            collectionDescription = base;
+            break;
+          }
+        }
+      }
+      if (!description) {
+        // Report the error for the top level schematic collection
+        throw new UnknownSchematicException(name, collection.description);
+      }
     }
 
-    const factory = this._host.getSchematicRuleFactory(description, collection.description);
+    const factory = this._host.getSchematicRuleFactory(description, collectionDescription);
     schematic = new SchematicImpl<CollectionT, SchematicT>(description, factory, collection, this);
 
     schematicMap.set(name, schematic);
 
     return schematic;
   }
 
-  listSchematicNames(collection: Collection<CollectionT, SchematicT>) {
-    return this._host.listSchematicNames(collection.description);
+  listSchematicNames(collection: Collection<CollectionT, SchematicT>): string[] {
+    const names = this._host.listSchematicNames(collection.description);
+
+    if (collection.baseDescriptions) {
+      for (const base of collection.baseDescriptions) {
+        names.push(...this._host.listSchematicNames(base));
+      }
+    }
+
+    // remove duplicates
+    return [...new Set(names)];
   }
 
   transformOptions<OptionT extends object, ResultT extends object>(

packages/angular_devkit/schematics/src/engine/interface.ts

@@ -19,6 +19,7 @@ import { TaskConfigurationGenerator, TaskExecutor, TaskId } from './task';
  */
 export type CollectionDescription<CollectionMetadataT extends object> = CollectionMetadataT & {
   readonly name: string;
+  readonly extends?: string[];
 };
 
 /**
@@ -49,7 +50,7 @@ export interface EngineHost<CollectionMetadataT extends object, SchematicMetadat
   createSchematicDescription(
       name: string,
       collection: CollectionDescription<CollectionMetadataT>):
-        SchematicDescription<CollectionMetadataT, SchematicMetadataT>;
+        SchematicDescription<CollectionMetadataT, SchematicMetadataT> | null;
   getSchematicRuleFactory<OptionT extends object>(
       schematic: SchematicDescription<CollectionMetadataT, SchematicMetadataT>,
       collection: CollectionDescription<CollectionMetadataT>): RuleFactory<OptionT>;
@@ -108,6 +109,7 @@ export interface Engine<CollectionMetadataT extends object, SchematicMetadataT e
  */
 export interface Collection<CollectionMetadataT extends object, SchematicMetadataT extends object> {
   readonly description: CollectionDescription<CollectionMetadataT>;
+  readonly baseDescriptions?: Array<CollectionDescription<CollectionMetadataT>>;
 
   createSchematic(name: string): Schematic<CollectionMetadataT, SchematicMetadataT>;
   listSchematicNames(): string[];

packages/angular_devkit/schematics/tools/fallback-engine-host.ts

@@ -68,8 +68,11 @@ export class FallbackEngineHost implements EngineHost<{}, {}> {
   createSchematicDescription(
     name: string,
     collection: CollectionDescription<FallbackCollectionDescription>,
-  ): SchematicDescription<FallbackCollectionDescription, FallbackSchematicDescription> {
+  ): SchematicDescription<FallbackCollectionDescription, FallbackSchematicDescription> | null {
     const description = collection.host.createSchematicDescription(name, collection.description);
+    if (!description) {
+      return null;
+    }
 
     return { name, collection, description };
   }

packages/angular_devkit/schematics/tools/file-system-engine-host-base.ts

@@ -20,7 +20,6 @@ import {
   Source,
   TaskExecutor,
   TaskExecutorFactory,
-  UnknownSchematicException,
   UnregisteredTaskException,
 } from '../src';
 import {
@@ -142,6 +141,11 @@ export abstract class FileSystemEngineHostBase implements
       throw new InvalidCollectionJsonException(name, path);
     }
 
+    // normalize extends property to an array
+    if (typeof jsonValue['extends'] === 'string') {
+      jsonValue['extends'] = [jsonValue['extends']];
+    }
+
     const description = this._transformCollectionDescription(name, {
       ...jsonValue,
       path,
@@ -169,7 +173,7 @@ export abstract class FileSystemEngineHostBase implements
   createSchematicDescription(
     name: string,
     collection: FileSystemCollectionDesc,
-  ): FileSystemSchematicDesc {
+  ): FileSystemSchematicDesc | null {
     // Resolve aliases first.
     for (const schematicName of Object.keys(collection.schematics)) {
       const schematicDescription = collection.schematics[schematicName];
@@ -180,13 +184,13 @@ export abstract class FileSystemEngineHostBase implements
     }
 
     if (!(name in collection.schematics)) {
-      throw new UnknownSchematicException(name, collection);
+      return null;
     }
 
     const collectionPath = dirname(collection.path);
     const partialDesc: Partial<FileSystemSchematicDesc> | null = collection.schematics[name];
     if (!partialDesc) {
-      throw new UnknownSchematicException(name, collection);
+      return null;
     }
 
     if (partialDesc.extends) {

packages/angular_devkit/schematics/tools/file-system-engine-host_spec.ts

@@ -39,6 +39,163 @@ describe('FileSystemEngineHost', () => {
     expect(schematic1.description.name).toBe('schematic1');
   });
 
+  it('lists schematics but not aliases', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    const testCollection = engine.createCollection('aliases');
+    const names = testCollection.listSchematicNames();
+
+    expect(names).not.toBeNull();
+    expect(names[0]).toBe('schematic1');
+    expect(names[1]).toBe('schematic2');
+  });
+
+  it('extends a collection with string', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    const testCollection = engine.createCollection('extends-basic-string');
+
+    expect(testCollection.baseDescriptions).not.toBeUndefined();
+    expect(testCollection.baseDescriptions
+           && testCollection.baseDescriptions.length).toBe(1);
+
+    const schematic1 = engine.createSchematic('schematic1', testCollection);
+
+    expect(schematic1).not.toBeNull();
+    expect(schematic1.description.name).toBe('schematic1');
+
+    const schematic2 = engine.createSchematic('schematic2', testCollection);
+
+    expect(schematic2).not.toBeNull();
+    expect(schematic2.description.name).toBe('schematic2');
+
+    const names = testCollection.listSchematicNames();
+
+    expect(names.length).toBe(2);
+  });
+
+  it('extends a collection with array', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    const testCollection = engine.createCollection('extends-basic');
+
+    expect(testCollection.baseDescriptions).not.toBeUndefined();
+    expect(testCollection.baseDescriptions
+           && testCollection.baseDescriptions.length).toBe(1);
+
+    const schematic1 = engine.createSchematic('schematic1', testCollection);
+
+    expect(schematic1).not.toBeNull();
+    expect(schematic1.description.name).toBe('schematic1');
+
+    const schematic2 = engine.createSchematic('schematic2', testCollection);
+
+    expect(schematic2).not.toBeNull();
+    expect(schematic2.description.name).toBe('schematic2');
+
+    const names = testCollection.listSchematicNames();
+
+    expect(names.length).toBe(2);
+  });
+
+  it('extends a collection with full depth', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    const testCollection = engine.createCollection('extends-deep');
+
+    expect(testCollection.baseDescriptions).not.toBeUndefined();
+    expect(testCollection.baseDescriptions
+           && testCollection.baseDescriptions.length).toBe(2);
+
+    const schematic1 = engine.createSchematic('schematic1', testCollection);
+
+    expect(schematic1).not.toBeNull();
+    expect(schematic1.description.name).toBe('schematic1');
+
+    const schematic2 = engine.createSchematic('schematic2', testCollection);
+
+    expect(schematic2).not.toBeNull();
+    expect(schematic2.description.name).toBe('schematic2');
+
+    const names = testCollection.listSchematicNames();
+
+    expect(names.length).toBe(2);
+  });
+
+  it('replaces base schematics when extending', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    const testCollection = engine.createCollection('extends-replace');
+
+    expect(testCollection.baseDescriptions).not.toBeUndefined();
+    expect(testCollection.baseDescriptions
+           && testCollection.baseDescriptions.length).toBe(1);
+
+    const schematic1 = engine.createSchematic('schematic1', testCollection);
+
+    expect(schematic1).not.toBeNull();
+    expect(schematic1.description.name).toBe('schematic1');
+    expect(schematic1.description.description).toBe('replaced');
+
+    const names = testCollection.listSchematicNames();
+
+    expect(names).not.toBeNull();
+    expect(names.length).toBe(1);
+  });
+
+  it('extends multiple collections', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    const testCollection = engine.createCollection('extends-multiple');
+
+    expect(testCollection.baseDescriptions).not.toBeUndefined();
+    expect(testCollection.baseDescriptions
+           && testCollection.baseDescriptions.length).toBe(4);
+
+    const schematic1 = engine.createSchematic('schematic1', testCollection);
+
+    expect(schematic1).not.toBeNull();
+    expect(schematic1.description.name).toBe('schematic1');
+    expect(schematic1.description.description).toBe('replaced');
+
+    const schematic2 = engine.createSchematic('schematic2', testCollection);
+
+    expect(schematic2).not.toBeNull();
+    expect(schematic2.description.name).toBe('schematic2');
+
+    const names = testCollection.listSchematicNames();
+
+    expect(names).not.toBeNull();
+    expect(names.length).toBe(2);
+  });
+
+  it('errors on simple circular collections', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    expect(() => engine.createCollection('extends-circular')).toThrow();
+  });
+
+  it('errors on complex circular collections', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    expect(() => engine.createCollection('extends-circular-multiple')).toThrow();
+  });
+
+  it('errors on deep circular collections', () => {
+    const engineHost = new FileSystemEngineHost(root);
+    const engine = new SchematicEngine(engineHost);
+
+    expect(() => engine.createCollection('extends-circular-deep')).toThrow();
+  });
+
   it('errors on invalid aliases', () => {
     const engineHost = new FileSystemEngineHost(root);
     const engine = new SchematicEngine(engineHost);

tests/@angular_devkit/schematics/tools/file-system-engine-host/extends-basic-string/collection.json

@@ -0,0 +1,10 @@
+{
+  "name": "extends-basic-string",
+  "extends": "works",
+  "schematics": {
+    "schematic2": {
+      "description": "2",
+      "factory": "../null-factory"
+    }
+  }
+}