update readme for instructions

packages/target-graph/README.md

@@ -2,22 +2,48 @@
 
 This package is concerned about the target graph. The target is a unit of work that gets spawned in a child process eventually be a scheduler + target runner. The main focus of this package are:
 
-1. Target interface
+1. `Target` interface.
-2. converter that changes from target ID to package + task, and vice versa
+2. converter that changes from target ID to package + task, and vice versa.
-3. A `TargetGraphBuilder` that will take in `PackageInfos` object with some task (dependency) configuration and builds a direct-acyclic graph of the targets.
+3. A simple `TargetGraphBuilder` that handles prioritization, cycle detection, subgraph generation.
+4. A workspace-aware `WorkspaceTargetGraphBuilder` that will take in `PackageInfos` object with some task (dependency) configuration and builds a direct-acyclic graph of the targets.
+5. A `TargetFactory` that can generate "global" or "package" level `Target`s.
 
-## TargetGraphBuilder usage
+## WorkspaceTargetGraphBuilder usage
+
+For the case (the typical `lage` CLI case) where we want to use the shorthand syntax to specify a task graph combining with a package dependency graph, this is the right Builder implementation.
 
 ```typescript
 const rootDir = getWorkspaceRoot(process.cwd());
 const packageInfos = getPackageInfos(rootDir);
 
-const builder = new TargetGraphBuilder(rootDir, packageInfos);
+const builder = new WorkspaceTargetGraphBuilder(rootDir, packageInfos);
 
 const tasks = ["build", "test"];
 const packages = ["package-a", "package-b"];
 
-const targetGraph = builder.buildTargetGraph(tasks, packages);
+builder.addTargetConfig("build", {
+  dependsOn: ["^build"],
+});
+
+const targetGraph = builder.build(tasks, packages);
+```
+
+## TargetGraphBuilder usage
+
+```typescript
+const builder = new TargetGraphBuilder();
+
+const target1 = {...};
+const target2 = {...};
+const target3 = {...};
+
+builder.addTarget(target1);
+builder.addTarget(target2);
+builder.addTarget(target3);
+
+builder.addDependency(target1.id, target2.id);
+
+const graph = builder.build();
 ```
 
 The resultant `targetGraph` will have a signature of this shape:
@@ -29,6 +55,21 @@ interface TargetGraph {
 }
 ```
 
+### TargetFactory usage
+
+```typescript
+const root = "/some/repo/root";
+const resolver = (packageName: string) => {
+  return `packages/${packageName}`;
+};
+
+const factory = new TargetFactory({ root, resolver });
+
+const target = factory.createPackageTarget("a", "build", {
+  ... // `TargetConfig`
+});
+```
+
 ### `Target`
 
-This is merely an interface that contains enough information to let the runner & scheduler know what to run. The "how" of how to run a target resides in the scheduler and a separate runner implementation.
+This is merely an interface that contains enough information to let the runner & scheduler know what to run. The "how" of how to run a target resides in the scheduler and a separate runner implementation.