nx-lifecycle 0.2.0 → 1.0.0

package/.npmignore

@@ -0,0 +1,20 @@
+CHANGELOG.md
+project.json
+tsconfig.json
+
+coverage/**
+eslint.config.js
+
+dist/tsconfig.tsbuildinfo
+dist/**/*.map
+dist-test/**
+test/**
+
+src/**
+!src/executors/lifecycle/schema.json
+
+dist/file-content.js
+dist/file-content.d.ts
+
+dist/executors/lifecycle/schema.js
+dist/executors/lifecycle/schema.d.ts

package/README.md

@@ -8,92 +8,140 @@ An [Nx](https://nx.dev/) plugin that injects specific targets into high level wo
 
 </div>
 
-## Table of Contents
-
-- [Introduction](#introduction)
-- [Usage](#usage)
-- [API](#api)
+## Contents
+
+- [Install](#install)
+- [Plugin](#plugin)
+    - [Overriding inferred targets](#overriding-inferred-targets)
+    - [Limitations](#limitations)
+    - [Migrating from the executor](#migrating-from-the-executor)
+- [Executor](#executor)
+- [Configuration](#configuration)
+    - [stages](#stages)
+    - [bindings](#bindings)
     - [check](#check)
     - [dryRun](#dryrun)
+- [CLI](#cli)
+
+For the problem this solves and design rationale, see [WHY-NX-LIFECYCLE.md](./WHY-NX-LIFECYCLE.md).
 
-## Introduction
+## Install
+
+```sh
+npm i -D nx-lifecycle
+```
 
-Nx targets achieve a specific task, such as loading external config, codegen, type checking, formatting, test execution or enforcing code coverage. 
+`nx-lifecycle` wires targets in one of two ways:
 
-Some of these tasks depend on each other, others can be executed in parallel.
+- **[Plugin](#plugin)** (recommended): infers the lifecycle targets whenever Nx builds the project graph. Nothing is written to files.
+- **[Executor](#executor)**: writes the lifecycle targets into `nx.json` and every `project.json`, to be committed. CI checks they are up to date.
 
-Nx uses the target's [dependsOn](https://nx.dev/reference/project-configuration#dependson) field to natively manage this, and will execute tasks whenever all dependencies are successfully complete.
+Both take the same [stages](#stages) and [bindings](#bindings).
 
-In practice, this quickly becomes unweildy. In order to properly configure a given task, you have to have full context about all other tasks (including those of your dependencies). You also need to make sure all dependents are updated whenever you add another step to a task.
+## Plugin
 
-For example, perhaps your code contains a typescript build step [nx-tsc](https://www.npmjs.com/package/nx-tsc), followed by a unit test [mocha](https://mochajs.org/). An initial config will look like:
+Add the plugin to `nx.json`, with stages and bindings as its options. Install `nx-lifecycle` in the workspace root `package.json`, where Nx resolves plugins.
 
 ```json
+// nx.json
 {
-    "targets": {
-        "nx-tsc": {
-            "dependsOn": ["^nx-tsc"]
-        },
-        "mocha": {
-            "dependsOn": ["nx-tsc"]
-        },
-    }
+    "plugins": [
+        {
+            "plugin": "nx-lifecycle/plugin",
+            "options": {
+                "stages": {
+                    "build": {
+                        "hooks": ["pre", "run", "post"],
+                        "dependsOn": ["^build"]
+                    },
+                    "test": {
+                        "hooks": ["run", "report"],
+                        "dependsOn": ["build"]
+                    }
+                },
+                "bindings": {
+                    "tsc": "build:run",
+                    "mocha": "test:run"
+                }
+            }
+        }
+    ]
 }
 ```
 
-Your mocha task depends on the nx-tsc first, and nx-tsc depends on any of _its_ dependencies to be built first.
+Every project with a `project.json` gets the [stage targets](#generated-targets). A bound target is wired in a project when its `project.json` declares it, e.g. `"tsc": {}`; the implementation can still come from `targetDefaults`. `nx show project <name>` lists the inferred targets.
 
-Now what if you need want to add a step _after_ to your build? Perhaps you want to use your recently built JS code to [generate a JSON config](https://www.npmjs.com/package/nx-populate-files).
+### Overriding inferred targets
 
-Now your mocha command needs to update to depend on that populate step, rather than `nx-tsc`. Your `nx-tsc` command _also_ needs to update its dependencies to depend on that task, rather than `nx-tsc`. But only if your dependencies include this populate step!
+Nx applies `nx.json` `targetDefaults` and `project.json` on top of inferred targets. A `dependsOn` there replaces the inferred one rather than merging with it. So:
 
-Instead of simply adding this new task, you now need to conditionally manage the dependecones on two other tasks! Imagine how this problem can grow as we begin to support more tasks like type checking, code coverage, or codegen. Each implemented slightly different in each package, especailly if you use more than one language in your monorepo!
+- Don't define the stage targets (`build`, `build:_`, `build:run`…) yourself.
+- If a bound target sets its own `dependsOn`, include its lifecycle dependency: the hook before its own, or `<stage>:_` for the first hook.
 
-`nx-lifecycle` is the solution to this problem, by breaking down the solution into two steps:
-
-### High level tasks
-
-We define abstract workflows that can optionally be used across any and all projects, regardless of language, purpose, or implementation.
-
-An example would breaking up general steps around a build/compile step, a formatter/linter, and test execution/coverage. We can fairly safely say that the build step will depend on our dependencies build steps, and test execution will depend on our own projects build step.
+```json
+// project.json, with "e2e-test": "test:run"
+{
+    "targets": {
+        "e2e-test": {
+            "dependsOn": [{ "target": "build", "projects": ["my-server"] }, "test:_"]
+        }
+    }
+}
+```
 
-Then we split up these high level tasks into even simpler tasks.
-An example would be our test suite may contain both unit-tests and functional tests, and then a final step to enforce the resulting code coverage achieves acceptable levels.
+Every time Nx builds the project graph, the plugin checks the merged configuration, and fails with the entry to add if a bound target lost its lifecycle dependency.
 
-Note these steps are still abstract, and it is not necessary that every project is capable of implementing every task.
+### Limitations
 
-### Bind implementions to tasks
+- Only projects with a `project.json` get lifecycle targets.
+- A target created by another Nx plugin is only wired if it is also declared in `project.json`.
+- Nx must load the plugin before it can build anything, so a workspace can't use the plugin from its own unbuilt source. Depend on a published version.
 
-Now we can bind project specific implementations to each abstract task.
+### Migrating from the executor
 
-In the original example, perhaps we bind our `nx-tsc` target to a `build:run` step, and our `nx-populate-files` step to a `build:post` step.
+1. Add the plugin to `nx.json`, with the options of the executor.
+2. Remove the `lifecycle` target that runs the executor.
+3. In `nx.json` `targetDefaults`, delete every target with a `__lifecycle` configuration, and remove lifecycle targets from the `dependsOn` of bound targets. Delete `dependsOn` if nothing else is left in it, as an empty list replaces the inferred one.
+4. Optionally delete the lifecycle targets (`"build:_": {}`…) from each `project.json`. They are empty, so they don't override anything.
+5. Run `nx show projects`. The plugin reports any target that still overrides its wiring.
 
-Then our `mocha` target can be bound to a `test:unit` step.
+## Executor
 
-You can bind multiple targets to a single step. For example if your code also includes some Java projects, you might also bind your [@nx/gradle](https://nx.dev/nx-api/gradle]) target to `build:run`.
+Register it as a target in a `project.json`. Because `lifecycle` manages dependencies for the rest of your targets, it should live in a project outside your normal build/test graph — for example, a root-level management package. See [Nx-lifecycle's own monorepo config](https://github.com/JacobLey/leyman/blob/main/leyman/main/lifecycle.json) for a real example.
 
-### Instrumenting your `nx.json` and `project.json`
+```json
+{
+    "targets": {
+        "lifecycle": {
+            "executor": "nx-lifecycle:lifecycle",
+            "options": {
+                "cwd": "{projectRoot}",
+                "configFile": "lifecycle.json"
+            }
+        }
+    }
+}
+```
 
-Now that you configured your abstract tasks and bound implementations, `nx-lifecycle` will update your `nx.json` and relevant `project.json` files will all the `dependsOn` to make your code run efficiently and deterministically!
+`nx-lifecycle` reads your stage and binding configuration, then writes `dependsOn` entries into `nx.json` and all relevant `project.json` files. The generated targets use the [noop](https://nx.dev/nx-api/nx/executors/noop) executor and should never be invoked directly or have their configuration edited by hand. Commit the generated output to version control, and rerun the executor whenever you add, remove, or rename targets.
 
-Any time you want to add or remove targets for a project, simply re-run `nx-lifecycle`'s plugin and all dependencies are up to date!
+You may declare any of your own targets as depending on a lifecycle-managed target. That is the intended use: your targets reference abstract stage targets, and `nx-lifecycle` ensures those stages wire up to the correct concrete implementations.
 
-## Installation
+Configuration can be provided in two ways:
 
-`npm i nx-lifecycle`
+- **Inline** — pass `stages` and `bindings` directly in the executor `options` inside `project.json`
+- **Config file** — point the executor at a separate JSON file (defaults to `lifecycle.json` in the project root)
 
-Register it as a target in a `project.json`:
 ```json
+// project.json — inline config
 {
     "targets": {
         "lifecycle": {
             "executor": "nx-lifecycle:lifecycle",
             "options": {
-                "cwd": "{projectRoot}",
-                "configFile": "lifecycle.json"
                 "stages": {
-                    "build": { 
-                        "hooks": ["pre", "run", "post"], 
+                    "build": {
+                        "hooks": ["pre", "run", "post"],
                         "dependsOn": ["^build"]
                     },
                     "test": {
@@ -111,49 +159,27 @@ Register it as a target in a `project.json`:
 }
 ```
 
-Note that this target only needs to be run once (not once per project) so it is recommended to put this somewhere like a root `project.json` to own this. [Nx-lifecycle's own monorepo is managed in a non-published "main" package](https://github.com/JacobLey/leyman/blob/main/leyman/main/lifecycle.json).
-
-## Usage
-
-Because `lifecycle` manages target dependencies itself, it probably should not be executed along with targets that are normally executed, like the `build` and `test` targets in the example above.
-
-For example, this project's use of `nx-lifecycle` is part of a [local-only project](https://github.com/JacobLey/leyman/blob/main/leyman/main/project.json#L15) that is never deployed anywhere, and exists only to manage the repo itself.
-
-`nx-lifecycle` will produce additional targets in your `nx.json` and `project.json`s. These will all be backed by the [noop](https://nx.dev/nx-api/nx/executors/noop) executor, and have no need to invoke caching. In fact, you should never directly manage these commands, their dependencies, or their configurations. These changes should be included in your version control.
-
-You may declare one-off targets that _depend_ on these targets though, that is the whole point! You should able to declare a target depends on the build step, without having to explicitly manage how the build script is implemented.
-
-`nx-lifecycle` will use the `nx.json` to assign defaults, and will assign defaults to your targets that are assigned there. However that does not guarantee every target is actually executable by every project. You must declare the target in your `project.json` as well. Do not worry about copying `nx-lifecycle`'s targets over.
-
-Instead of providing all the stages and bindings in the package.json file, it is also possible to manage that in a separate file, and point the plugin at it.
-
-### As a plugin
-
-Specify `nx-lifecycle:lifecycle` as the executor. You can pass the `lifecycle.json` config file there, or may provide the config JSON directly inline as the options.
-
 ```json
-// project.json
+// project.json — file-based config
 {
     "targets": {
         "lifecycle": {
             "executor": "nx-lifecycle:lifecycle",
             "options": {
                 "cwd": "{projectRoot}",
-                "configFile": "my-lifecycle-config.json" // defaults to "lifecycle.json"
+                "configFile": "my-lifecycle-config.json"
             }
         }
     }
 }
 ```
 
-Where the file is the options object
-
 ```json
-// lifecycle.json
+// lifecycle.json — the config file
 {
     "stages": {
-        "build": { 
-            "hooks": ["pre", "run", "post"], 
+        "build": {
+            "hooks": ["pre", "run", "post"],
             "dependsOn": ["^build"]
         },
         "test": {
@@ -168,81 +194,139 @@ Where the file is the options object
 }
 ```
 
-### As a CLI
-
-Alternatively, you may invoke this plugin as a CLI command. Similar to above, it is _recommended_ to include this dependency in some project that is outside the scope of your "normal" packages. Although it could conceptually be installed globally as well.
+## Configuration
 
-`pnpx nx-lifecycle --help`
-`pnpx nx-lifecycle --config-file ./my-lifecycle.json --dry-run`
+### `stages`
 
-It is not possible to pass the configuration directly to the CLI, and must use a config file.
+Required. No default.
 
-## Configuration
+Declares the abstract workflow stages that `nx-lifecycle` will own. Each key is a stage name; the value configures that stage's structure and upstream dependencies.
 
-Both the CLI and the plugin support providing a config file to manage lifecycle options. This file (defaults to `lifecycle.json`) contains configuraiton that specifies the different stages and bindings for your projects.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `hooks` | `string[]` | — | Ordered list of sub-steps within the stage. The resulting target names are `stage:hook` (e.g. `build:run`). If omitted, the stage has no sub-steps and is referenced directly by name. |
+| `dependsOn` | `dependsOn[]` | — | Upstream dependencies for this stage, using the same format as Nx's native [`dependsOn`](https://nx.dev/reference/project-configuration#dependson). Defines the relationship between this stage and others (or their upstream counterparts). |
 
-The lifecycle executor can also provide all these options directly in the `project.json` if preferred.
+**Note:** If a stage declares `hooks`, bindings must reference a specific hook (`build:run`), not the stage name alone (`build`).
 
-### configuration.stages
+```json
+{
+    "stages": {
+        "build": {
+            "hooks": ["pre", "run", "post"],
+            "dependsOn": ["^build"]
+        },
+        "test": {
+            "hooks": ["run", "report"],
+            "dependsOn": ["build"]
+        }
+    }
+}
+```
 
-Required. No default value.
+A stage without hooks (referenced directly by name):
 
-This is the [high level tasks](#high-level-tasks) logic as described above. Declares the generic targets to be owned by `nx-lifecycle`, which represent workflows with potentially multiple steps.
+```json
+{
+    "stages": {
+        "build": {
+            "dependsOn": ["^build"]
+        }
+    },
+    "bindings": {
+        "tsc": "build"
+    }
+}
+```
 
-It is an object, where every key is the name of a stage. The value is another object that optionally has two fields:
+#### Generated targets
 
-- `steps`
-  - A list of "sub-stages" to be executed in order. The resulting name of the target will be delimeted by a colon: `stage:step`.
-- `dependsOn`
-  - Accepts the same values as normal Nx [dependsOn](https://nx.dev/reference/project-configuration#dependson). Used to define relationship between stages, and their dependencies.
+Each stage generates a chain of `noop` targets. For `build` with hooks `pre`, `run`, `post`:
 
-### configuration.bindings
+```
+build:_ → build:pre → build:run → build:post → build
+```
 
-Required. No default value.
+- `build:_` is the stage's **anchor**. It carries the stage's `dependsOn`, so every hook waits for it. Nothing can be bound to it.
+- Each hook depends on the previous one, and a bound target depends on the hook before its own. Targets bound to the same hook run in parallel.
+- `build` is the stage's public entry point. Other stages and your own targets should depend on it, not on its hooks.
 
-This is [bind implementions to tasks](#bind-implementions-to-tasks) logic as described above.
+### `bindings`
 
-The value is an object mapping, where the key is the name of your specific target implementations (e.g. `nx-tsc` or `mocha`) and the value is the stage it maps to.
+Required. No default.
 
-__\*\*NOTE\*\*__ If the bound stage has `steps` defined, then you must bind to a specific step. If there are no steps, then you reference the stage directly.
+Maps your project's concrete target names to lifecycle stage hooks. Each key is the name of an existing Nx target (e.g. `tsc`, `mocha`); the value is the stage or stage hook it should be bound to.
 
 ```json
-// lifecycle.json
 {
-    "stages": {
-        "build": { 
-            "dependsOn": ["^build"]
-        },
-        "test": {
-            "hooks": ["run", "report"],
-            "dependsOn": ["build"]
-        }
-    },
     "bindings": {
-        "tsc": "build",
+        "tsc": "build:run",
         "mocha": "test:run"
     }
 }
 ```
 
-### configuration.check
+Multiple targets from different languages or toolchains can bind to the same hook:
+
+```json
+{
+    "bindings": {
+        "tsc": "build:run",
+        "gradle": "build:run"
+    }
+}
+```
+
+A binding applies to every project that defines the target, through `targetDefaults` or its own `project.json`. A project opts in by defining it (e.g. `"tsc": {}`). A warning is logged for a binding that no `project.json` declares, since it is usually a typo. Targets inferred by Nx plugins are not declared in `project.json`, so they trigger the warning too.
 
-`boolean`. Default `true` in CI environments, otherwise `false`.
+#### Project-specific dependencies
 
-If `true`, the executor will fail if the `nx.json` or any `project.json` is out of sync with what `nx-lifecycle` believes is correct.
+With the plugin, see [Overriding inferred targets](#overriding-inferred-targets) instead. With the executor, a project can't change a stage's `dependsOn`, but it can add dependencies to its own bound targets. `nx-lifecycle` keeps any `dependsOn` entry that isn't a lifecycle target and appends the hook dependency after it:
 
-Useful for ensuring that generated configs are up to date in version control before proceeding with deployments.
+```json
+// project.json
+{
+    "targets": {
+        "e2e-test": {
+            "dependsOn": [{ "target": "build", "projects": ["my-server"] }]
+        }
+    }
+}
+```
 
-### configuration.dryRun
+Use this sparingly. If many projects need the same dependency, it belongs in the stage.
 
-`boolean`. Default `false`.
+### `check`
 
-If `true`, will do everything except actually write the updated config files.
+Executor only.
 
-Can still fail if `check` is `true`.
+| Type | Default |
+|------|---------|
+| `boolean` | `true` in CI, `false` otherwise |
 
-## Executors
+When `true`, the executor fails if `nx.json` or any `project.json` is out of sync with what `nx-lifecycle` would generate. Use this in CI to verify that generated configs are committed and up to date before deployment proceeds.
 
-### lifecycle
+### `dryRun`
+
+Executor only.
+
+| Type | Default |
+|------|---------|
+| `boolean` | `false` |
+
+When `true`, performs all computation but skips writing any files. Can still fail when `check` is `true`.
+
+## CLI
+
+`nx-lifecycle` can also be invoked directly as a CLI command. Configuration must be provided via a config file — inline options are not supported from the CLI.
+
+```sh
+pnpx nx-lifecycle --help
+pnpx nx-lifecycle --config-file ./my-lifecycle.json --dry-run
+```
 
-Will update all `project.json`s and the `nx.json` with declared stages, and wire up dependencies to your bound targets, ensuring that you can reference your abstract targets, Nx will invoke the required targets in dependency order as necessary.
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--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. |

package/WHY-NX-LIFECYCLE.md

@@ -0,0 +1,64 @@
+<div style="text-align:center">
+
+# Why nx-lifecycle?
+
+</div>
+
+## The Problem
+
+Nx's `dependsOn` field is powerful — it lets you declare that a target must wait for other targets to complete before it runs. But as a monorepo grows, managing those dependencies by hand becomes a significant maintenance burden.
+
+### Manual `dependsOn` doesn't scale
+
+Consider a simple setup: a TypeScript build step (`tsc`) followed by a unit test runner (`mocha`).
+
+```json
+{
+    "targets": {
+        "tsc": {
+            "dependsOn": ["^tsc"]
+        },
+        "mocha": {
+            "dependsOn": ["tsc"]
+        }
+    }
+}
+```
+
+This is fine. `mocha` waits for `tsc`, and `tsc` waits for its upstream dependencies to build first.
+
+Now you need to add a post-build step — say, a [`populate-files`](https://www.npmjs.com/package/load-populate-files) step that uses the freshly-compiled JS to generate a JSON config.
+
+The new step must run after `tsc` but before `mocha`. So:
+
+- `mocha` must now depend on `populate-files`, not `tsc`
+- `tsc` must now depend on the upstream `populate-files` of _its_ dependencies (but only for packages that actually have that step)
+
+Adding one new target required updating the dependency declarations on two existing targets — and conditionally, depending on what each dependency package implements. In a monorepo with dozens of packages and targets, every new step multiplies the update surface.
+
+### The compounding problem
+
+The situation gets worse as the repo grows:
+
+- Different packages implement targets differently (TypeScript vs Java vs Go)
+- Some packages have `populate-files`, others don't
+- A new `lint`, `typecheck`, or `codegen` step in one package requires auditing every other package's `dependsOn` to see what needs updating
+- There is no single place to reason about the _intended_ order of operations — it's spread across every `project.json`
+
+The `dependsOn` fields become a tangled web of implementation details rather than a clear expression of intent.
+
+---
+
+## The Solution
+
+`nx-lifecycle` separates the _what_ from the _how_:
+
+1. **Stages** — You declare abstract, high-level workflows once (e.g. `build` with hooks `pre`, `run`, `post`; `test` with hooks `run`, `report`). These stages express the _intended_ order of operations, independent of any specific tooling.
+
+2. **Bindings** — You declare once which concrete targets (e.g. `tsc`, `eslint`) map to which stage and hook. Each project opts in by defining those targets. The mapping lives with the tool, not scattered across every dependent.
+
+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.
+
+Now you can just run `nx run <project>:build` and let the projects determine what "building" means to it.