nx-lifecycle 1.1.4 → 1.2.0

package/README.md

@@ -14,7 +14,7 @@ Declare your workflow once — `build` runs hooks `pre` → `run` → `post`, `t
 - **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.
 
-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).
+Guides and the full reference are on the [docs site](https://jacobley.github.io/leyman/packages/nx-lifecycle/). 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
 
@@ -44,7 +44,7 @@ npm i -D nx-lifecycle
 - **[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.
 
-Both take the same [stages](#stages) and [bindings](#bindings).
+Both take the same [stages](#stages) and [bindings](#bindings). Requires Node.js 24 or later. `nx` and `@nx/devkit` (`^23.3.0`) are regular dependencies of `nx-lifecycle` (not peers), so use the same Nx major version in the workspace.
 
 ## Plugin
 
@@ -77,7 +77,9 @@ Add the plugin to `nx.json`, with stages and bindings as its options. Install `n
 }
 ```
 
-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.
+The options are typed as `LifecyclePluginOptions`: `import type { LifecyclePluginOptions } from 'nx-lifecycle/plugin'`, e.g. `const options = { stages, bindings } satisfies LifecyclePluginOptions;`.
+
+Every project with a `project.json` gets the [stage targets](#generated-targets), even if it declares nothing bound to them. 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.
 
 ### Overriding inferred targets
 
@@ -213,9 +215,11 @@ Declares the abstract workflow stages that `nx-lifecycle` will own. Each key is
 | 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). |
+| `dependsOn` | `dependsOn[]` | — | Upstream dependencies for this stage, using the same format as Nx's native [`dependsOn`](https://nx.dev/reference/project-configuration#dependson): `"build"` (this project's stage), `"^build"` (the stage of every dependency project), `{ "target": "build", "projects": ["my-server"] }`. Can name a stage or any other target, but not another stage's anchor or hook (`^build:post` is rejected: depend on `build`). |
+
+**Note:** If a stage declares `hooks`, bindings must reference a specific hook (`build:run`), not the stage name alone (`build`). A stage without hooks still generates an anchor: `lint:_ → eslint → lint`.
 
-**Note:** If a stage declares `hooks`, bindings must reference a specific hook (`build:run`), not the stage name alone (`build`).
+The config is checked whenever Nx builds the project graph, and fails for a binding that names a hook that doesn't exist, a stage that has hooks, an anchor (`build:_`) or a lifecycle target, and for a stage `dependsOn` on another stage's anchor or hook.
 
 ```json
 {
@@ -312,7 +316,7 @@ Executor only.
 |------|---------|
 | `boolean` | `true` in CI, `false` otherwise |
 
-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.
+When `true`, the executor writes nothing and 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.
 
 ### `dryRun`
 
@@ -326,7 +330,7 @@ When `true`, performs all computation but skips writing any files. Can still fai
 
 ## 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.
+`nx-lifecycle` installs an `nx-lifecycle` command (also available as `lifecycle`). It does what the executor does. Configuration must be provided via a config file — inline options are not supported from the CLI.
 
 ```sh
 pnpx nx-lifecycle --help
@@ -337,7 +341,8 @@ 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. |
+| `--check`, `--ci` | `boolean` | `true` in CI | Fail if any file is out of sync. |
+| `--cwd` | `string` | `.` | Directory other paths are resolved from. |
 
 ### `explain`
 

package/WHY-NX-LIFECYCLE.md

@@ -6,7 +6,7 @@
 
 ## 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.
+Nx's `dependsOn` field 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
 
@@ -61,4 +61,4 @@ The `dependsOn` fields become a tangled web of implementation details rather tha
 
 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.
+Now `nx run <project>:build` runs whatever "building" means for each project.

package/dist/cli.js

@@ -12,7 +12,7 @@ export class LifecycleCli {
                 type: 'json'
             }
         });
-        let cli = yargs().scriptName('lifecycle').option({
+        let cli = yargs().scriptName('nx-lifecycle').option({
             cwd: {
                 type: 'string',
                 default: '.',

package/dist/executors/lifecycle/lifecycle.js

@@ -2,9 +2,9 @@ import { lifecycleInternal } from '../../lifecycle/lifecycle-internal.js';
 export const lifecycle = async (options, context)=>{
     await lifecycleInternal(options, {
         root: context.root,
-        projects: Object.values(context.projectsConfigurations.projects).map((projectConfig)=>({
-                name: projectConfig.name,
-                root: projectConfig.root
+        projects: Object.entries(context.projectsConfigurations.projects).map(([name, { root }])=>({
+                name,
+                root
             }))
     });
     return {

package/dist/lifecycle/explain.js

@@ -39,7 +39,7 @@ const resolveUpstream = (graph, projectName, target)=>{
 };
 const explainDependency = (graph, projectName, dependency)=>{
     const { target, dependencies, projects } = normalizeDependency(dependency);
-    if (dependencies) {
+    if (dependencies === true) {
         return {
             label: `^${target}`,
             upstream: resolveUpstream(graph, projectName, target)
@@ -93,7 +93,7 @@ export const explainLifecycle = ({ plan, graph, project, stage })=>{
     const stageDependencies = new Map();
     for (const stageName of stageNames){
         const anchor = plan.lifecycleTargets.get(`${stageName}:_`);
-        stageDependencies.set(stageName, anchor.dependsOn.map((dependency)=>normalizeDependency(dependency)).filter(({ target, dependencies, projects })=>!dependencies && projects === undefined && stageNames.includes(target)).map(({ target })=>target));
+        stageDependencies.set(stageName, anchor.dependsOn.map((dependency)=>normalizeDependency(dependency)).filter(({ target, dependencies, projects })=>dependencies !== true && projects === undefined && stageNames.includes(target)).map(({ target })=>target));
     }
     const explainTarget = (targetName, previousHook)=>({
             name: targetName,

package/dist/lifecycle/normalizer.d.ts

@@ -16,7 +16,7 @@ export interface NormalizedOptions {
  *
  * @param options - options, or where to load them from
  * @returns stages and bindings, with any options passed directly
- * @throws {Error} when the config file is invalid
+ * @rejects {Error} when the config file is invalid
  */
 export declare const loadOptions: (options: LifecycleOptionsOrConfig) => Promise<LifecycleOptions>;
 /**

package/dist/lifecycle/processor.d.ts

@@ -36,7 +36,7 @@ export interface LifecyclePlan {
  *
  * @param options - stages and bindings
  * @returns lifecycle targets and bound targets
- * @throws if stages or bindings are inconsistent
+ * @throws {Error} if stages or bindings are inconsistent
  */
 export declare const planLifecycle: (options: ProcessorOptions) => LifecyclePlan;
 export declare const processNxAndProjectJsons: ({ nxJson, projectJsons, options, }: {

package/dist/lifecycle/processor.js

@@ -76,7 +76,7 @@ const calculateTargetsToRemove = ({ lifecycleTargets, nxJson })=>{
     return targetsToRemove;
 };
 const getDependencyTarget = (dependency)=>typeof dependency === 'string' ? dependency : dependency.target;
-const normalizeDependencyTarget = (dependencyTarget)=>dependencyTarget.replace(/^\^/u, '');
+const normalizeDependencyTarget = (dependencyTarget)=>dependencyTarget.replace(/^\^/v, '');
 const removeDependencyTargets = ({ target, targetsToRemove })=>(target.dependsOn ?? []).filter((dependency)=>!targetsToRemove.has(normalizeDependencyTarget(getDependencyTarget(dependency))));
 const validateLifecycleDependencies = ({ lifecycleTargets, options })=>{
     for (const [stageName, { dependsOn }] of Object.entries(options.stages)){
@@ -131,7 +131,8 @@ const processNxJson = ({ nxJson, lifecycleTargets, registeredTargets, targetsToR
         lifecycles[targetName] = {
             executor: NOOP_EXECUTOR,
             dependsOn: [
-                ...target.dependsOn
+                ...target.dependsOn,
+                ...registeredTargets.entries().filter(([, { name }])=>name === targetName).map(([boundTarget])=>boundTarget)
             ],
             configurations: {
                 __lifecycle: {}
@@ -159,7 +160,6 @@ const processNxJson = ({ nxJson, lifecycleTargets, registeredTargets, targetsToR
         const registeredTarget = targetDefaults[targetName] ?? {};
         registeredTarget.dependsOn ??= [];
         registeredTarget.dependsOn.push(lifecycleTarget.previousHook);
-        lifecycles[lifecycleTarget.name].dependsOn?.push(targetName);
         targetDefaults[targetName] = registeredTarget;
     }
     Object.assign(targetDefaults, lifecycles);

package/dist/plugin/lifecycle-plugin.js

@@ -69,22 +69,22 @@ const createProjectNode = (projectJsonPath, { lifecycleTargets, registeredTarget
     assertProjectJson(projectJson);
     const declaredTargets = projectJson.targets ?? {};
     const targets = {};
+    const boundTargets = [
+        ...registeredTargets
+    ].filter(([targetName])=>Object.hasOwn(declaredTargets, targetName));
     for (const [targetName, lifecycleTarget] of lifecycleTargets){
         targets[targetName] = {
             executor: NOOP_EXECUTOR,
             dependsOn: [
-                ...lifecycleTarget.dependsOn
+                ...lifecycleTarget.dependsOn,
+                ...boundTargets.filter(([, { name }])=>name === targetName).map(([boundTarget])=>boundTarget)
             ],
             metadata: {
                 description: describeTarget(lifecycleTarget)
             }
         };
     }
-    for (const [targetName, lifecycleTarget] of registeredTargets){
-        if (!Object.hasOwn(declaredTargets, targetName)) {
-            continue;
-        }
-        targets[lifecycleTarget.name].dependsOn.push(targetName);
+    for (const [targetName, lifecycleTarget] of boundTargets){
         targets[targetName] = {
             dependsOn: [
                 lifecycleTarget.previousHook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-lifecycle",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "description": "Nx plugin that derives every dependsOn from declared lifecycle stages (build, test, …) and the targets bound to them.",
   "engines": {
     "node": ">=24"
@@ -13,7 +13,7 @@
     "url": "git+https://github.com/JacobLey/leyman.git",
     "directory": "apps/nx-lifecycle"
   },
-  "homepage": "https://github.com/JacobLey/leyman/tree/main/apps/nx-lifecycle#readme",
+  "homepage": "https://jacobley.github.io/leyman/packages/nx-lifecycle/",
   "bugs": {
     "url": "https://github.com/JacobLey/leyman/issues"
   },
@@ -56,21 +56,22 @@
     "#internal/*": "./dist/*"
   },
   "bin": {
-    "lifecycle": "./bin.mjs"
+    "lifecycle": "./bin.mjs",
+    "nx-lifecycle": "./bin.mjs"
   },
   "dependencies": {
     "@nx/devkit": "^23.3.0",
     "ci-info": "^4.4.0",
-    "entry-script": "^4.1.1",
-    "fast-equals": "^6.0.4",
-    "format-file": "^1.0.3",
-    "haywire": "^2.0.2",
-    "haywire-launcher": "^1.1.0",
-    "juniper": "^2.4.1",
-    "juniper-validator": "^0.5.0",
+    "entry-script": "^4.1.2",
+    "fast-equals": "^6.2.1",
+    "format-file": "^1.1.0",
+    "haywire": "^2.0.4",
+    "haywire-launcher": "^1.1.1",
+    "juniper": "^2.5.0",
+    "juniper-validator": "^0.5.1",
     "nx": "^23.3.0",
-    "parse-cwd": "^2.0.2",
-    "unknown-error": "^0.1.0",
+    "parse-cwd": "^2.0.3",
+    "unknown-error": "^0.1.1",
     "yargs": "^18.2.0"
   },
   "devDependencies": {
@@ -78,19 +79,19 @@
     "@leyman/eslint-config": "^0.0.1",
     "@leyman/expect": "^0.0.1",
     "@swc/cli": "^0.8.1",
-    "@swc/core": "^1.16.2",
+    "@swc/core": "^1.16.18",
     "@types/mocha": "^10.0.10",
     "@types/node": "^24.19.0",
     "@types/sinon": "^22.0.0",
     "@types/yargs": "^17.0.35",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "barrelify": "^2.2.1",
+    "barrelify": "^2.2.2",
     "c8": "^12.0.0",
-    "eslint": "^10.12.0",
+    "eslint": "^10.13.0",
     "expect-type": "^1.4.0",
-    "load-populate-files": "^1.1.2",
-    "mocha": "^12.0.2",
-    "mocha-chain": "^1.0.1",
+    "load-populate-files": "^1.1.3",
+    "mocha": "^12.0.3",
+    "mocha-chain": "^1.0.2",
     "sinon": "^22.1.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2"
   }