feat(@angular/schematics): implement the schematics library

This is not including a README, which will come later.

Author: hansl

packages/schematics/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@angular/schematics",
+  "version": "0.0.0",
+  "description": "CLI tool for Angular",
+  "main": "src/index.js",
+  "typings": "src/index.d.ts",
+  "keywords": [
+    "angular",
+    "sdk",
+    "blueprints",
+    "code generation",
+    "schematics",
+    "Angular SDK"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/angular/sdk.git"
+  },
+  "engines": {
+    "node": ">= 6.9.0",
+    "npm": ">= 3.0.0"
+  },
+  "author": "Angular Authors",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/angular/sdk/issues"
+  },
+  "homepage": "https://github.com/angular/sdk",
+  "dependencies": {
+  }
+}

packages/schematics/src/engine/collection.ts

@@ -0,0 +1,53 @@
+import {SchematicEngine} from './engine';
+import {Collection, CollectionDescription, Schematic, SchematicDescription} from './interface';
+import {BaseException} from '../exception/exception';
+
+
+
+export class UnknownSchematicNameException extends BaseException {
+  constructor(collection: string, name: string) {
+    super(`Schematic named "${name}" could not be found in collection "${collection}".`);
+  }
+}
+export class InvalidSchematicException extends BaseException {
+  constructor(name: string) { super(`Invalid schematic: "${name}".`); }
+}
+
+
+export class CollectionImpl implements Collection {
+  private _schematics: { [name: string]: (options: any) => Schematic | null } = {};
+
+  constructor(private _description: CollectionDescription,
+              private _engine: SchematicEngine) {
+    Object.keys(this._description.schematics).forEach(name => {
+      this._schematics[name] = (options: any) => this._engine.createSchematic(name, this, options);
+    });
+  }
+
+  get engine() { return this._engine; }
+  get name() { return this._description.name || '<unknown>'; }
+  get path() { return this._description.path || '<unknown>'; }
+
+  listSchematicNames(): string[] {
+    return Object.keys(this._schematics);
+  }
+
+  getSchematicDescription(name: string): SchematicDescription | null {
+    if (!(name in this._description.schematics)) {
+      return null;
+    }
+    return this._description.schematics[name];
+  }
+
+  createSchematic<T>(name: string, options: T): Schematic {
+    if (!(name in this._schematics)) {
+      throw new UnknownSchematicNameException(this.name, name);
+    }
+
+    const schematic = this._schematics[name](options);
+    if (!schematic) {
+      throw new InvalidSchematicException(name);
+    }
+    return schematic;
+  }
+}

packages/schematics/src/engine/context.ts

@@ -0,0 +1,16 @@
+import {Engine, Schematic, SchematicContext} from './interface';
+import {MergeStrategy, Tree} from '../tree/interface';
+
+import {Observable} from 'rxjs/Observable';
+
+
+export class SchematicContextImpl implements SchematicContext {
+  constructor(private _schematic: Schematic,
+              private _host: Observable<Tree>,
+              private _strategy = MergeStrategy.Default) {}
+
+  get host() { return this._host; }
+  get engine(): Engine { return this._schematic.collection.engine; }
+  get schematic() { return this._schematic; }
+  get strategy() { return this._strategy; }
+}

packages/schematics/src/engine/engine.ts

@@ -0,0 +1,81 @@
+import {CollectionImpl} from './collection';
+import {
+  Collection,
+  CollectionDescription,
+  Engine,
+  ProtocolHandler,
+  ResolvedSchematicDescription,
+  Schematic,
+  SchematicContext,
+  Source
+} from './interface';
+import {SchematicImpl} from './schematic';
+import {BaseException} from '../exception/exception';
+import {empty} from '../tree/static';
+
+import {Url, parse, format} from 'url';
+
+
+export class InvalidSourceUrlException extends BaseException {
+  constructor(url: string) { super(`Invalid source url: "${url}".`); }
+}
+export class UnknownUrlSourceProtocol extends BaseException {
+  constructor(url: string) { super(`Unknown Protocol on url "${url}".`); }
+}
+
+
+export interface SchematicEngineOptions {
+  loadCollection(name: string): CollectionDescription | null;
+  loadSchematic<T>(name: string,
+                   collection: Collection,
+                   options: T): ResolvedSchematicDescription | null;
+}
+
+
+export class SchematicEngine implements Engine {
+  private _protocolMap = new Map<string, ProtocolHandler>();
+
+  constructor(private _options: SchematicEngineOptions) {
+    // Default implementations.
+    this._protocolMap.set('null', () => {
+      return () => empty();
+    });
+    this._protocolMap.set('', (url: Url) => {
+      // Make a copy, change the protocol.
+      const fileUrl = parse(format(url));
+      fileUrl.protocol = 'file:';
+      return (context: SchematicContext) => context.engine.createSourceFromUrl(fileUrl)(context);
+    });
+  }
+
+  createCollection(name: string): Collection | null {
+    const description = this._options.loadCollection(name);
+    if (!description) {
+      return null;
+    }
+
+    return new CollectionImpl(description, this);
+  }
+
+  createSchematic<T>(name: string, collection: Collection, options: T): Schematic | null {
+    const description = this._options.loadSchematic<T>(name, collection, options);
+    if (!description) {
+      return null;
+    }
+
+    return new SchematicImpl(description, collection);
+  }
+
+  registerUrlProtocolHandler(protocol: string, handler: ProtocolHandler) {
+    this._protocolMap.set(protocol, handler);
+  }
+
+  createSourceFromUrl(url: Url): Source {
+    const protocol = (url.protocol || '').replace(/:$/, '');
+    const handler = this._protocolMap.get(protocol);
+    if (!handler) {
+      throw new UnknownUrlSourceProtocol(url.toString());
+    }
+    return handler(url);
+  }
+}

packages/schematics/src/engine/interface.ts

@@ -0,0 +1,73 @@
+import {MergeStrategy, Tree} from '../tree/interface';
+
+import {Observable} from 'rxjs/Observable';
+import {Url} from 'url';
+
+
+export interface Schematic {
+  readonly name: string;
+  readonly description: string;
+  readonly path: string;
+  readonly collection: Collection;
+
+  call(host: Observable<Tree>, parentContext: Partial<SchematicContext>): Observable<Tree>;
+}
+
+
+export interface ProtocolHandler {
+  (url: Url): Source;
+}
+
+
+
+export interface Engine {
+  createCollection(name: string): Collection | null;
+  createSchematic<T>(name: string, collection: Collection, options: T): Schematic | null;
+  registerUrlProtocolHandler(protocol: string, handler: ProtocolHandler): void;
+  createSourceFromUrl(url: Url): Source;
+}
+
+
+export interface Collection {
+  readonly engine: Engine;
+  readonly name: string;
+  readonly path: string;
+
+  listSchematicNames(): string[];
+  getSchematicDescription(name: string): SchematicDescription | null;
+  createSchematic<T>(name: string, options: T): Schematic;
+}
+
+
+export interface SchematicContext {
+  readonly engine: Engine;
+  readonly schematic: Schematic;
+  readonly host: Observable<Tree>;
+  readonly strategy: MergeStrategy;
+}
+
+
+export interface CollectionDescription {
+  readonly path: string;
+  readonly name?: string;
+  readonly version?: string;
+  readonly schematics: { [name: string]: SchematicDescription };
+}
+
+export interface SchematicDescription {
+  readonly factory: string;
+  readonly description: string;
+  readonly schema?: string;
+}
+
+
+export interface ResolvedSchematicDescription extends SchematicDescription {
+  readonly name: string;
+  readonly path: string;
+  readonly rule: Rule;
+}
+
+export type RuleFactory<T> = (options: T) => Rule;
+
+export type Source = (context: SchematicContext) => Tree | Observable<Tree>;
+export type Rule = (tree: Tree, context: SchematicContext) => Tree | Observable<Tree>;

packages/schematics/src/engine/schematic.ts

@@ -0,0 +1,44 @@
+import {SchematicContextImpl} from './context';
+import {Collection, ResolvedSchematicDescription, Schematic, SchematicContext} from './interface';
+import {MergeStrategy, Tree} from '../tree/interface';
+import {BaseException} from '../exception/exception';
+
+import {Observable} from 'rxjs/Observable';
+import 'rxjs/add/observable/fromPromise';
+import 'rxjs/add/observable/of';
+import 'rxjs/add/operator/concatMap';
+
+
+export class InvalidSchematicsNameException extends BaseException {
+  constructor(path: string, name: string) {
+    super(`Schematics at path "${path}" has invalid name "${name}".`);
+  }
+}
+
+
+export class SchematicImpl implements Schematic {
+  constructor(private _descriptor: ResolvedSchematicDescription,
+              private _collection: Collection) {
+    if (!_descriptor.name.match(/^[-_.a-zA-Z0-9]+$/)) {
+      throw new InvalidSchematicsNameException(_descriptor.path, _descriptor.name);
+    }
+  }
+
+  get name() { return this._descriptor.name; }
+  get description() { return this._descriptor.description; }
+  get path() { return this._descriptor.path; }
+  get collection() { return this._collection; }
+
+  call(host: Observable<Tree>, parentContext: Partial<SchematicContext>): Observable<Tree> {
+    const context = new SchematicContextImpl(this, host,
+        parentContext.strategy || MergeStrategy.Default);
+    return host.concatMap(tree => {
+      const result = this._descriptor.rule(tree, context);
+      if (result instanceof Observable) {
+        return result;
+      } else {
+        return Observable.of(result);
+      }
+    });
+  }
+}

packages/schematics/src/engine/schematic_spec.ts

@@ -0,0 +1,63 @@
+import {ResolvedSchematicDescription} from './interface';
+import {SchematicImpl} from './schematic';
+import {Tree} from '../tree/interface';
+import {branch, empty} from '../tree/static';
+
+import 'rxjs/add/operator/toArray';
+import 'rxjs/add/operator/toPromise';
+import {Observable} from 'rxjs/Observable';
+
+
+
+describe('Schematic', () => {
+  it('works with a rule', done => {
+    let inner: any = null;
+    const desc: ResolvedSchematicDescription = {
+      name: 'test',
+      description: '',
+      factory: '',
+      path: 'a/b/c',
+      rule: (tree: Tree) => {
+        inner = branch(tree);
+        tree.create('a/b/c', 'some content');
+        return tree;
+      }
+    };
+
+    const schematic = new SchematicImpl(desc, null !);
+
+    schematic.call(Observable.of(empty()), {})
+      .toPromise()
+      .then(x => {
+        expect(inner.files).toEqual([]);
+        expect(x.files).toEqual(['/a/b/c']);
+      })
+      .then(done, done.fail);
+  });
+
+  it('works with a rule that returns an observable', done => {
+    let inner: any = null;
+    const desc: ResolvedSchematicDescription = {
+      name: 'test',
+      description: '',
+      factory: '',
+      path: 'a/b/c',
+      rule: (fem: Tree) => {
+        inner = fem;
+        return Observable.of(empty());
+      }
+    };
+
+
+    const schematic = new SchematicImpl(desc, null !);
+    schematic.call(Observable.of(empty()), {})
+      .toPromise()
+      .then(x => {
+        expect(inner.files).toEqual([]);
+        expect(x.files).toEqual([]);
+        expect(inner).not.toBe(x);
+      })
+      .then(done, done.fail);
+  });
+
+});

packages/schematics/src/exception/exception.ts

@@ -0,0 +1,24 @@
+// Starting with TS 2.1, Error cannot be properly extended anymore, so we implement the same
+// interface but in a different package.
+export class BaseException extends Error {
+  constructor(message = '') {
+    super(message);
+  }
+}
+
+
+// Exceptions
+export class FileDoesNotExistException extends BaseException {
+  constructor(path: string) { super(`Path "${path}" does not exist.`); }
+}
+export class FileAlreadyExistException extends BaseException {
+  constructor(path: string) { super(`Path "${path}" already exist.`); }
+}
+export class ContentHasMutatedException extends BaseException {
+  constructor(path: string) {
+    super(`Content at path "${path}" has changed between the start and the end of an update.`);
+  }
+}
+export class InvalidUpdateRecordException extends BaseException {
+  constructor() { super(`Invalid record instance.`); }
+}