feat(@angular-devkit/architect): New Architect API first draft

The new API has been described in this design doc:
https://docs.google.com/document/d/1SpN_2XEooI9_CPjqspAcNEBjVY874OWPZqOenjuF0qo/view

This first drafts add support for the API (given some deep imports). It is
still in draft mode but is committed to make it available to people to
start testing and moving their own builders.

This API rebuilds (not backward compatible) the Architect API package. To
use it people will need to import "@angular-devkit/architect/src/index2"
to start using it. A reference builder will be added in the next commit.

There are 2 pieces missing from this commit that will be added in the
same PR; 1) the architect-host and CLI to test, and 2) a reference
builder moved from the old API to the new one. These will be part of
the same PR.

Finally, there are missing tests in this package, but everything tested
manually and automatically works so far. Test coverage will be added
before the package is considered finished.

Due to a desire to keep architect, our tests and the scope of this PR
limited and keep the two APIs separated, every clashing files will
have a "2" suffix added to it. Once all builders have been moved and
we are sure everything works, all those files will be moved to their
final destination and the old API will be removed, in one PR.

Author: hansl

etc/api/angular_devkit/architect/src/index.d.ts renamed to etc/api/angular_devkit/architect/src/_golden-api.d.ts

@@ -7,9 +7,27 @@ licenses(["notice"])  # MIT
 
 load("@build_bazel_rules_typescript//:defs.bzl", "ts_library")
 load("@build_bazel_rules_nodejs//:defs.bzl", "npm_package")
+load("//tools:ts_json_schema.bzl", "ts_json_schema")
 
 package(default_visibility = ["//visibility:public"])
 
+ts_json_schema(
+    name = "builder_input_schema",
+    src = "src/input-schema.json",
+)
+ts_json_schema(
+    name = "builder_output_schema",
+    src = "src/output-schema.json",
+)
+ts_json_schema(
+    name = "builder_builders_schema",
+    src = "src/builders-schema.json",
+)
+ts_json_schema(
+    name = "progress_schema",
+    src = "src/progress-schema.json",
+)
+
 ts_library(
     name = "architect",
     srcs = glob(
@@ -29,6 +47,9 @@ ts_library(
         "@rxjs",
         "@rxjs//operators",
         "@npm//@types/node",
+        ":builder_input_schema",
+        ":builder_output_schema",
+        ":progress_schema",
     ],
 )
 

packages/angular_devkit/architect/BUILD

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright Google Inc. 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 './architect-legacy';
+// export * from './api';
+// export { Architect, ScheduleOptions } from './architect';
+// export { createBuilder } from './create-builder';

packages/angular_devkit/architect/src/_golden-api.d.ts

@@ -0,0 +1,230 @@
+/**
+ * @license
+ * Copyright Google Inc. 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 { experimental, json, logging } from '@angular-devkit/core';
+import { Observable } from 'rxjs';
+import { Schema as RealBuilderInput, Target as RealTarget } from './input-schema';
+import { Schema as RealBuilderOutput } from './output-schema';
+import { Schema as RealBuilderProgress, State as BuilderProgressState } from './progress-schema';
+
+export type Target = json.JsonObject & RealTarget;
+export {
+  BuilderProgressState,
+};
+
+// Type short hands.
+export type BuilderRegistry =
+  experimental.jobs.Registry<json.JsonObject, BuilderInput, BuilderOutput>;
+
+
+/**
+ * An API typed BuilderProgress. The interface generated from the schema is too permissive,
+ * so this API is the one we show in our API. Please note that not all fields are in there; this
+ * is in addition to fields in the schema.
+ */
+export type TypedBuilderProgress = (
+    { state: BuilderProgressState.Stopped; }
+  | { state: BuilderProgressState.Error; error: json.JsonValue; }
+  | { state: BuilderProgressState.Waiting; status?: string; }
+  | { state: BuilderProgressState.Running; status?: string; current: number; total?: number; }
+);
+
+/**
+ * Declaration of those types as JsonObject compatible. JsonObject is not compatible with
+ * optional members, so those wouldn't be directly assignable to our internal Json typings.
+ * Forcing the type to be both a JsonObject and the type from the Schema tells Typescript they
+ * are compatible (which they are).
+ * These types should be used everywhere.
+ */
+export type BuilderInput = json.JsonObject & RealBuilderInput;
+export type BuilderOutput = json.JsonObject & RealBuilderOutput;
+export type BuilderProgress = json.JsonObject & RealBuilderProgress & TypedBuilderProgress;
+
+/**
+ * A progress report is what the tooling will receive. It contains the builder info and the target.
+ * Although these are serializable, they are only exposed through the tooling interface, not the
+ * builder interface. The watch dog sends BuilderProgress and the Builder has a set of functions
+ * to manage the state.
+ */
+export type BuilderProgressReport = BuilderProgress & ({
+  target?: Target;
+  builder: BuilderInfo;
+});
+
+/**
+ * A Run, which is what is returned by scheduleBuilder or scheduleTarget functions. This should
+ * be reconstructed across memory boundaries (it's not serializable but all internal information
+ * are).
+ */
+export interface BuilderRun {
+  /**
+   * Unique amongst runs. This is the same ID as the context generated for the run. It can be
+   * used to identify multiple unique runs. There is no guarantee that a run is a single output;
+   * a builder can rebuild on its own and will generate multiple outputs.
+   */
+  id: number;
+
+  /**
+   * The builder information.
+   */
+  info: BuilderInfo;
+
+  /**
+   * The next output from a builder. This is recommended when scheduling a builder and only being
+   * interested in the result of that single run, not of a watch-mode builder.
+   */
+  result: Promise<BuilderOutput>;
+
+  /**
+   * The output(s) from the builder. A builder can have multiple outputs.
+   * This always replay the last output when subscribed.
+   */
+  output: Observable<BuilderOutput>;
+
+  /**
+   * The progress report. A progress also contains an ID, which can be different than this run's
+   * ID (if the builder calls scheduleBuilder or scheduleTarget).
+   * This will always replay the last progress on new subscriptions.
+   */
+  progress: Observable<BuilderProgressReport>;
+
+  /**
+   * Stop the builder from running. Returns a promise that resolves when the builder is stopped.
+   * Some builders might not handle stopping properly and should have a timeout here.
+   */
+  stop(): Promise<void>;
+}
+
+/**
+ * The context received as a second argument in your builder.
+ */
+export interface BuilderContext {
+  /**
+   * Unique amongst contexts. Contexts instances are not guaranteed to be the same (but it could
+   * be the same context), and all the fields in a context could be the same, yet the builder's
+   * context could be different. This is the same ID as the corresponding run.
+   */
+  id: number;
+
+  /**
+   * The builder info that called your function. Since the builder info is from the builder.json
+   * (or the host), it could contain information that is different than expected.
+   */
+  builder: BuilderInfo;
+
+  /**
+   * A logger that appends messages to a log. This could be a separate interface or completely
+   * ignored. `console.log` could also be completely ignored.
+   */
+  logger: logging.LoggerApi;
+
+  /**
+   * The absolute workspace root of this run. This is a system path and will not be normalized;
+   * ie. on Windows it will starts with `C:\\` (or whatever drive).
+   */
+  workspaceRoot: string;
+
+  /**
+   * The current directory the user is in. This could be outside the workspace root. This is a
+   * system path and will not be normalized; ie. on Windows it will starts with `C:\\` (or
+   * whatever drive).
+   */
+  currentDirectory: string;
+
+  /**
+   * The target that was used to run this builder.
+   * Target is optional if a builder was ran using `scheduleBuilder()`.
+   */
+  target?: Target;
+
+  /**
+   * Schedule a target in the same workspace. This can be the same target that is being executed
+   * right now, but targets of the same name are serialized.
+   * Running the same target and waiting for it to end will result in a deadlocking scenario.
+   * Targets are considered the same if the project, the target AND the configuration are the same.
+   * @param target The target to schedule.
+   * @param overrides A set of options to override the workspace set of options.
+   * @return A promise of a run. It will resolve when all the members of the run are available.
+   */
+  scheduleTarget(
+    target: Target,
+    overrides?: json.JsonObject,
+  ): Promise<BuilderRun>;
+
+  /**
+   * Schedule a builder by its name. This can be the same builder that is being executed.
+   * @param builderName The name of the builder, ie. its `packageName:builderName` tuple.
+   * @param options All options to use for the builder (by default empty object). There is no
+   *     additional options added, e.g. from the workspace.
+   * @return A promise of a run. It will resolve when all the members of the run are available.
+   */
+  scheduleBuilder(
+    builderName: string,
+    options?: json.JsonObject,
+  ): Promise<BuilderRun>;
+
+  /**
+   * Set the builder to running. This should be used if an external event triggered a re-run,
+   * e.g. a file watched was changed.
+   */
+  reportRunning(): void;
+
+  /**
+   * Update the status string shown on the interface.
+   * @param status The status to set it to. An empty string can be used to remove the status.
+   */
+  reportStatus(status: string): void;
+
+  /**
+   * Update the progress for this builder run.
+   * @param current The current progress. This will be between 0 and total.
+   * @param total A new total to set. By default at the start of a run this is 1. If omitted it
+   *     will use the same value as the last total.
+   * @param status Update the status string. If omitted the status string is not modified.
+   */
+  reportProgress(current: number, total?: number, status?: string): void;
+}
+
+
+/**
+ * An accepted return value from a builder. Can be either an Observable, a Promise or a vector.
+ */
+export type BuilderOutputLike = Observable<BuilderOutput> | Promise<BuilderOutput> | BuilderOutput;
+
+
+/**
+ * A builder handler function. The function signature passed to `createBuilder()`.
+ */
+export interface BuilderHandlerFn<A extends json.JsonObject> {
+  /**
+   * Builders are defined by users to perform any kind of task, like building, testing or linting,
+   * and should use this interface.
+   * @param input The options (a JsonObject), validated by the schema and received by the
+   *     builder. This can include resolved options from the CLI or the workspace.
+   * @param context A context that can be used to interact with the Architect framework.
+   * @return One or many builder output.
+   */
+  (input: A, context: BuilderContext): BuilderOutputLike;
+}
+
+/**
+ * A Builder general information. This is generated by the host and is expanded by the host, but
+ * the public API contains those fields.
+ */
+export type BuilderInfo = json.JsonObject & {
+  builderName: string;
+  description: string;
+  optionSchema: json.schema.JsonSchema;
+};
+
+
+/**
+ * Returns a string of "project:target[:configuration]" for the target object.
+ */
+export function targetStringFromTarget({project, target, configuration}: Target) {
+  return `${project}:${target}${configuration !== undefined ? ':' + configuration : ''}`;
+}