lage/packages/target-graph

@lage-run/target-graph

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.
2. converter that changes from target ID to package + task, and vice versa.
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 Targets.

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.

const rootDir = getWorkspaceRoot(process.cwd());
const packageInfos = getPackageInfos(rootDir);

const builder = new WorkspaceTargetGraphBuilder(rootDir, packageInfos);

const tasks = ["build", "test"];
const packages = ["package-a", "package-b"];

builder.addTargetConfig("build", {
  dependsOn: ["^build"],
});

const targetGraph = builder.build(tasks, packages);

TargetGraphBuilder usage

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:

interface TargetGraph {
  targets: Map<string, Target>;
  dependencies: [string, string][];
}

TargetFactory usage

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.