nx-lifecycle 0.2.1 → 1.0.0

package/dist/plugin/dependencies.js

@@ -0,0 +1,9 @@
+import { logger, readJsonFile } from '@nx/devkit';
+import { bind, createModule, identifier } from 'haywire';
+import { assertProjectJson, assertProjectJsonIdentifier } from '#schemas';
+import { assertLifecyclePluginOptions, assertLifecyclePluginOptionsId } from './schema.js';
+export const pluginLoggerId = identifier();
+export const readJsonFileId = identifier();
+export const pluginDependenciesModule = createModule(bind(pluginLoggerId).withInstance(logger)).addBinding(bind(readJsonFileId).withInstance(readJsonFile)).addBinding(bind(assertProjectJsonIdentifier).withInstance(assertProjectJson)).addBinding(bind(assertLifecyclePluginOptionsId).withInstance(assertLifecyclePluginOptions));
+
+//# sourceMappingURL=dependencies.js.map

package/dist/plugin/index.d.ts

@@ -0,0 +1,283 @@
+export type { LifecyclePluginOptions } from './schema.js';
+/**
+ * Plugin name, as Nx can't attach one to an ES module.
+ */
+export declare const name = "nx-lifecycle";
+export declare const createNodes: import("@nx/devkit").CreateNodes<Partial<{
+    stages: Record<string, Partial<{
+        dependsOn: (string | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string))[];
+        hooks: string[];
+    }>>;
+    bindings: Record<string, string>;
+}> & Required<Pick<{
+    stages: Record<string, Partial<{
+        dependsOn: (string | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string))[];
+        hooks: string[];
+    }>>;
+    bindings: Record<string, string>;
+}, "bindings" | "stages">>>, createDependencies: (options: (Partial<{
+    stages: Record<string, Partial<{
+        dependsOn: (string | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string))[];
+        hooks: string[];
+    }>>;
+    bindings: Record<string, string>;
+}> & Required<Pick<{
+    stages: Record<string, Partial<{
+        dependsOn: (string | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: boolean;
+            projects: never;
+        }> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (string & Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">>) | (Partial<{
+            dependencies: never;
+            projects: string | string[];
+        }> & Required<Pick<{
+            dependencies: never;
+            projects: string | string[];
+        }, "projects">> & Partial<{
+            target: string;
+            params: string;
+        }> & Required<Pick<{
+            target: string;
+            params: string;
+        }, "target">> & string))[];
+        hooks: string[];
+    }>>;
+    bindings: Record<string, string>;
+}, "bindings" | "stages">>) | undefined, context: import("@nx/devkit").CreateDependenciesContext) => [];
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.js

@@ -0,0 +1,6 @@
+import { lifecyclePluginContainer } from './container.js';
+import { LifecyclePlugin } from './lifecycle-plugin.js';
+export const name = 'nx-lifecycle';
+export const { createNodes, createDependencies } = lifecyclePluginContainer.get(LifecyclePlugin);
+
+//# sourceMappingURL=index.js.map

package/dist/plugin/lifecycle-plugin.d.ts

@@ -0,0 +1,21 @@
+import type { CreateDependencies, CreateNodes } from '@nx/devkit';
+import type { AssertProjectJson } from '#schemas';
+import type { PluginLogger, ReadJsonFile } from './dependencies.js';
+import type { AssertLifecyclePluginOptions, LifecyclePluginOptions } from './schema.js';
+/**
+ * Nx plugin that infers lifecycle targets, instead of writing them to `nx.json` and `project.json`.
+ *
+ * `createNodes` adds the anchor, hook and stage targets to every project with a `project.json`,
+ * and wires the bound targets declared there.
+ *
+ * Nx applies `nx.json` `targetDefaults` and `project.json` on top of inferred targets,
+ * replacing `dependsOn` rather than merging it.
+ * `createDependencies` runs on the merged configuration, and fails if a bound target lost its wiring.
+ */
+export declare class LifecyclePlugin {
+    #private;
+    readonly createNodes: CreateNodes<LifecyclePluginOptions>;
+    readonly createDependencies: (...args: Parameters<CreateDependencies<LifecyclePluginOptions>>) => [];
+    constructor(assertOptions: AssertLifecyclePluginOptions, readJsonFile: ReadJsonFile, assertProjectJson: AssertProjectJson, logger: PluginLogger);
+}
+//# sourceMappingURL=lifecycle-plugin.d.ts.map

package/dist/plugin/lifecycle-plugin.js

@@ -0,0 +1,158 @@
+import Path from 'node:path';
+import { createNodesFromFiles } from '@nx/devkit';
+import { deepEqual } from 'fast-equals';
+import { NOOP_EXECUTOR } from '../lifecycle/constants.js';
+import { planLifecycle } from '../lifecycle/processor.js';
+const describeTarget = ({ kind, name, stage })=>{
+    if (kind === 'anchor') {
+        return `Start of the ${stage} stage. Waits for the dependencies of the stage`;
+    }
+    if (kind === 'hook') {
+        return `Runs the targets bound to ${name}`;
+    }
+    return `Runs the ${stage} stage`;
+};
+const normalizeDependency = (dependency)=>{
+    if (typeof dependency !== 'string') {
+        return dependency;
+    }
+    if (dependency.startsWith('^')) {
+        return {
+            target: dependency.slice(1),
+            dependencies: true
+        };
+    }
+    return {
+        target: dependency
+    };
+};
+const dependsOnIncludes = (dependsOn, expected)=>{
+    const normalizedExpected = normalizeDependency(expected);
+    return (dependsOn ?? []).some((dependency)=>deepEqual(normalizeDependency(dependency), normalizedExpected));
+};
+const validateProject = ({ targets = {} }, { lifecycleTargets, registeredTargets })=>{
+    const errors = [];
+    for (const [targetName, lifecycleTarget] of lifecycleTargets){
+        const target = targets[targetName];
+        if (target && (target.executor !== NOOP_EXECUTOR || !lifecycleTarget.dependsOn.every((dependency)=>dependsOnIncludes(target.dependsOn, dependency)))) {
+            errors.push(`${targetName} is inferred by nx-lifecycle, but project.json or nx.json targetDefaults override it. Remove it from there`);
+        }
+    }
+    for (const [targetName, lifecycleTarget] of registeredTargets){
+        const target = targets[targetName];
+        const hook = targets[lifecycleTarget.name];
+        if (!target) {
+            continue;
+        }
+        if (!hook) {
+            errors.push(`${targetName} is bound to ${lifecycleTarget.name}, but nx-lifecycle only adds lifecycle targets to projects with a project.json. Add one`);
+        } else if (!dependsOnIncludes(hook.dependsOn, targetName)) {
+            errors.push(`${targetName} is bound to ${lifecycleTarget.name}, but is not declared in project.json. Declare it there so nx-lifecycle can wire it`);
+        } else if (!dependsOnIncludes(target.dependsOn, lifecycleTarget.previousHook)) {
+            errors.push(`${targetName} is bound to ${lifecycleTarget.name}, so it must depend on ${lifecycleTarget.previousHook}. A dependsOn in project.json or nx.json targetDefaults replaces the inferred one, so add "${lifecycleTarget.previousHook}" to it`);
+        }
+    }
+    return errors;
+};
+export class LifecyclePlugin {
+    #assertOptions;
+    #readJsonFile;
+    #assertProjectJson;
+    #logger;
+    createNodes;
+    createDependencies;
+    constructor(assertOptions, readJsonFile, assertProjectJson, logger){
+        this.#assertOptions = assertOptions;
+        this.#readJsonFile = readJsonFile;
+        this.#assertProjectJson = assertProjectJson;
+        this.#logger = logger;
+        this.createNodes = [
+            '**/project.json',
+            this.#createNodes.bind(this)
+        ];
+        this.createDependencies = this.#createDependencies.bind(this);
+    }
+    #plan(options) {
+        try {
+            this.#assertOptions(options);
+        } catch (err) {
+            const issues = err.cause;
+            throw new Error([
+                'Invalid nx-lifecycle plugin options in nx.json:',
+                ...issues.map(({ instancePath, message })=>`- options${instancePath} ${message}`)
+            ].join('\n'), {
+                cause: err
+            });
+        }
+        return planLifecycle(options);
+    }
+    async #createNodes(projectJsonPaths, options, context) {
+        const plan = this.#plan(options);
+        return createNodesFromFiles((projectJsonPath)=>this.#createProjectNode(projectJsonPath, plan, context), projectJsonPaths, options, context);
+    }
+    #createProjectNode(projectJsonPath, { lifecycleTargets, registeredTargets }, context) {
+        const projectJson = this.#readJsonFile(Path.join(context.workspaceRoot, projectJsonPath));
+        this.#assertProjectJson(projectJson);
+        const declaredTargets = projectJson.targets ?? {};
+        const targets = {};
+        for (const [targetName, lifecycleTarget] of lifecycleTargets){
+            targets[targetName] = {
+                executor: NOOP_EXECUTOR,
+                dependsOn: [
+                    ...lifecycleTarget.dependsOn
+                ],
+                metadata: {
+                    description: describeTarget(lifecycleTarget)
+                }
+            };
+        }
+        for (const [targetName, lifecycleTarget] of registeredTargets){
+            if (targetName in declaredTargets) {
+                targets[lifecycleTarget.name].dependsOn.push(targetName);
+                targets[targetName] = {
+                    dependsOn: [
+                        lifecycleTarget.previousHook
+                    ]
+                };
+            }
+        }
+        return {
+            projects: {
+                [Path.dirname(projectJsonPath)]: {
+                    targets
+                }
+            }
+        };
+    }
+    #createDependencies(options, context) {
+        const plan = this.#plan(options);
+        const errors = new Map();
+        const definedTargets = new Set();
+        for (const [projectName, project] of Object.entries(context.projects)){
+            for (const error of validateProject(project, plan)){
+                const projectNames = errors.get(error) ?? [];
+                projectNames.push(projectName);
+                errors.set(error, projectNames);
+            }
+            for (const targetName of Object.keys(project.targets ?? {})){
+                definedTargets.add(targetName);
+            }
+        }
+        if (errors.size > 0) {
+            throw new Error([
+                'nx-lifecycle targets are not wired as configured:',
+                ...[
+                    ...errors
+                ].map(([error, projectNames])=>`- ${error}\n  Projects: ${projectNames.join(', ')}`)
+            ].join('\n'));
+        }
+        for (const targetName of plan.registeredTargets.keys()){
+            if (!definedTargets.has(targetName)) {
+                this.#logger.warn(`Bound target ${targetName} is not defined in any project. Is it a typo?`);
+            }
+        }
+        return [];
+    }
+}
+
+//# sourceMappingURL=lifecycle-plugin.js.map