nx-lifecycle 1.0.0 → 1.1.1

package/README.md

@@ -1,13 +1,23 @@
 <div style="text-align:center">
 
 # nx-lifecycle
-An [Nx](https://nx.dev/) plugin that injects specific targets into high level workflows.
+[Nx](https://nx.dev/) plugin that derives every `dependsOn` from declared lifecycle stages (build, test, …) and the targets bound to them.
 
 [![npm package](https://badge.fury.io/js/nx-lifecycle.svg)](https://www.npmjs.com/package/nx-lifecycle)
-[![License](https://img.shields.io/npm/l/nx-lifecycle.svg)](https://github.com/JacobLey/leyman/blob/main/tools/nx-lifecycle/LICENSE)
+[![License](https://img.shields.io/npm/l/nx-lifecycle.svg)](https://github.com/JacobLey/leyman/blob/main/apps/nx-lifecycle/LICENSE)
 
 </div>
 
+Declare your workflow once — `build` runs hooks `pre` → `run` → `post`, `test` runs after `build` — then bind tools to hooks (`tsc` → `build:run`, `mocha` → `test:run`). Then `nx run <project>:build` runs the right steps, in the right order, in any project.
+
+- **Add a step in one place** — binding a new target (codegen, lint, a post-build step) rewires every dependent automatically, across every project.
+- **Per-project implementations** — each project opts into the bound targets it declares, so TypeScript, Go and Java projects can all answer to the same `build` and `test`.
+- **Nothing to commit** — the plugin infers targets when Nx builds the project graph, and fails with the fix if a project's `dependsOn` breaks the wiring. An executor that writes the config to files is also available.
+
+**Compared to** hand-written `dependsOn` in `targetDefaults` and each `project.json`: there, adding a step between two existing ones means editing every target that depended on the first, in every project that has it.
+
+For the problem this solves and design rationale, see [WHY-NX-LIFECYCLE.md](https://github.com/JacobLey/leyman/blob/main/apps/nx-lifecycle/WHY-NX-LIFECYCLE.md).
+
 ## Contents
 
 - [Install](#install)
@@ -22,8 +32,7 @@ An [Nx](https://nx.dev/) plugin that injects specific targets into high level wo
     - [check](#check)
     - [dryRun](#dryrun)
 - [CLI](#cli)
-
-For the problem this solves and design rationale, see [WHY-NX-LIFECYCLE.md](./WHY-NX-LIFECYCLE.md).
+    - [explain](#explain)
 
 ## Install
 
@@ -330,3 +339,32 @@ pnpx nx-lifecycle --config-file ./my-lifecycle.json --dry-run
 | `--config-file` | `string` | `lifecycle.json` | Path to the lifecycle config file. |
 | `--dry-run` | `boolean` | `false` | Compute changes without writing files. |
 | `--check` | `boolean` | `true` in CI | Fail if any file is out of sync. |
+
+### `explain`
+
+Prints what runs, in which order, for the stages of a project: each stage after the stages it depends on, its hooks, and the bound targets the project declares. A `^` dependency lists the upstream projects it runs.
+
+```sh
+pnpx nx-lifecycle explain my-lib       # every stage
+pnpx nx-lifecycle explain my-lib test  # test, and the stages it runs after
+```
+
+```
+my-lib
+
+1. build
+   after: ^build (my-utils)
+   build:pre (nothing bound)
+   build:run
+     tsc
+
+2. test
+   after: build
+   test:run
+     mocha
+     e2e-test (also after: my-server:build)
+   test:report
+     coverage-report
+```
+
+Stages and bindings come from the [plugin](#plugin) options in `nx.json`, or else from `--config-file` (default `lifecycle.json`). Bound targets and their other dependencies come from the project as Nx resolves it, after `targetDefaults` and `project.json`.

package/WHY-NX-LIFECYCLE.md

@@ -59,6 +59,6 @@ The `dependsOn` fields become a tangled web of implementation details rather tha
 
 3. **Wiring** — `nx-lifecycle` reads the stages and bindings, then derives every `dependsOn`: its Nx plugin infers them when Nx builds the project graph, or its executor writes them into `nx.json` and `project.json`.
 
-The result: adding a new step means updating one binding. Every downstream `dependsOn` is recomputed. The generated configs are checked into version control, so CI can verify they're in sync before any deployment proceeds.
+The result: adding a new step means updating one binding. Every downstream `dependsOn` is recomputed. With the plugin this happens every time Nx builds the project graph, so there is nothing to keep in sync. With the executor the generated configs are committed, and CI checks they are up to date.
 
 Now you can just run `nx run <project>:build` and let the projects determine what "building" means to it.