nx-lifecycle 1.0.0 → 1.1.0

package/dist/cli.js

@@ -1,43 +1,30 @@
 import yargs from 'yargs';
 import { EntryScript } from "entry-script";
+import { explainCommand } from './commands/explain-command.js';
+import { lifecycleCommand } from './commands/lifecycle-command.js';
 export class LifecycleCli extends EntryScript {
-    #getCommands;
-    #logger;
-    #errorLogger;
-    #exitCode;
-    constructor(getCommands, logger, errorLogger, exitCode){
-        super();
-        this.#getCommands = getCommands;
-        this.#logger = logger;
-        this.#errorLogger = errorLogger;
-        this.#exitCode = exitCode;
-    }
-    async main(argv) {
+    static async main(argv) {
         const packageJson = await import('../package.json', {
             with: {
                 type: 'json'
             }
         });
-        const yarg = yargs().scriptName('lifecycle').option({
+        await yargs().scriptName('lifecycle').option({
             cwd: {
                 type: 'string',
                 default: '.',
                 describe: 'Directory to resolve all other paths from'
             }
-        }).strict().help().alias('help', 'info').version(packageJson.default.version);
-        for (const command of this.#getCommands()){
-            yarg.command(command);
-        }
-        await yarg.parseAsync(argv, {}, this.#yargsOutput.bind(this));
+        }).strict().help().alias('help', 'info').version(packageJson.default.version).command(lifecycleCommand).command(explainCommand).parseAsync(argv, {}, LifecycleCli.#yargsOutput);
     }
-    #yargsOutput(e, _argv, log) {
+    static #yargsOutput(e, _argv, log) {
         if (e) {
-            this.#exitCode(1);
+            process.exitCode = 1;
             if (log) {
-                this.#errorLogger(log);
+                console.error(log);
             }
         } else if (log) {
-            this.#logger(log);
+            console.log(log);
         }
     }
 }

package/dist/commands/explain-command.d.ts

@@ -0,0 +1,12 @@
+import type { Command, LifecycleCommandInput } from './lib/types.js';
+interface ExplainCommandExtendedInput extends LifecycleCommandInput {
+    project: string;
+    stage: string | undefined;
+    configFile: string;
+}
+/**
+ * Prints the stages of a project in the order they run, with the targets bound to each hook.
+ */
+export declare const explainCommand: Command<ExplainCommandExtendedInput>;
+export {};
+//# sourceMappingURL=explain-command.d.ts.map

package/dist/commands/explain-command.js

@@ -0,0 +1,57 @@
+import Path from 'node:path';
+import { createProjectGraphAsync, readJsonFile, workspaceRoot } from '@nx/devkit';
+import { explainLifecycle, formatExplanation } from '../lifecycle/explain.js';
+import { loadOptions } from '../lifecycle/normalizer.js';
+import { planLifecycle } from '../lifecycle/processor.js';
+import { planPluginOptions } from '../plugin/lifecycle-plugin.js';
+const loadPlan = async ({ cwd, configFile })=>{
+    const { plugins = [] } = readJsonFile(Path.join(workspaceRoot, 'nx.json'));
+    const plugin = plugins.find((entry)=>typeof entry !== 'string' && entry.plugin === 'nx-lifecycle/plugin');
+    if (plugin) {
+        return planPluginOptions(plugin.options);
+    }
+    return planLifecycle(await loadOptions({
+        cwd,
+        configFile
+    }));
+};
+export const explainCommand = {
+    command: 'explain <project> [stage]',
+    describe: 'Print what runs, in which order, for the stages of a project',
+    builder: (yargs)=>yargs.positional('project', {
+            describe: 'Name of the Nx project',
+            type: 'string',
+            demandOption: true
+        }).positional('stage', {
+            describe: 'Only explain this stage, and the stages it runs after',
+            type: 'string'
+        }).options({
+            configFile: {
+                describe: 'Lifecycle config file, used when nx.json does not register the plugin',
+                type: 'string',
+                default: 'lifecycle.json'
+            }
+        }).strict(),
+    handler: async (options)=>{
+        const graph = await createProjectGraphAsync();
+        const plan = await loadPlan(options);
+        let explanation;
+        try {
+            explanation = explainLifecycle({
+                plan,
+                graph,
+                project: options.project,
+                ...options.stage === undefined ? {} : {
+                    stage: options.stage
+                }
+            });
+        } catch (err) {
+            console.error(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(formatExplanation(explanation));
+    }
+};
+
+//# sourceMappingURL=explain-command.js.map

package/dist/commands/lib/types.d.ts

@@ -3,7 +3,4 @@ export interface LifecycleCommandInput {
     cwd: string;
 }
 export type Command<ExtendedInput extends LifecycleCommandInput> = Pick<CommandModule<LifecycleCommandInput, ExtendedInput>, 'builder' | 'command' | 'describe' | 'handler'>;
-export interface AbstractCommand extends Pick<CommandModule<LifecycleCommandInput, LifecycleCommandInput>, 'builder' | 'command' | 'describe'> {
-    handler: (args: any) => Promise<void>;
-}
 //# sourceMappingURL=types.d.ts.map

package/dist/commands/lifecycle-command.d.ts

@@ -1,6 +1,3 @@
-import type { ProjectGraph } from '@nx/devkit';
-import type { Argv } from 'yargs';
-import type { ILifecycleInternal } from '../lifecycle/lifecycle-internal.js';
 import type { Command, LifecycleCommandInput } from './lib/types.js';
 interface LifecycleCommandExtendedInput extends LifecycleCommandInput {
     configFile: string;
@@ -10,13 +7,6 @@ interface LifecycleCommandExtendedInput extends LifecycleCommandInput {
 /**
  * Main `nx-lifecycle` command
  */
-export declare class LifecycleCommand implements Command<LifecycleCommandExtendedInput> {
-    #private;
-    readonly command: string[];
-    readonly describe = "Inject Nx targets as high level workflows";
-    constructor(getProjectGraph: () => Promise<ProjectGraph>, workspaceRoot: string, lifecycleInternal: ILifecycleInternal);
-    builder(this: void, yargs: Argv<LifecycleCommandInput>): Argv<LifecycleCommandExtendedInput>;
-    handler(options: LifecycleCommandExtendedInput): Promise<void>;
-}
+export declare const lifecycleCommand: Command<LifecycleCommandExtendedInput>;
 export {};
 //# sourceMappingURL=lifecycle-command.d.ts.map

package/dist/commands/lifecycle-command.js

@@ -1,21 +1,13 @@
+import { createProjectGraphAsync, workspaceRoot } from '@nx/devkit';
 import { isCI } from 'ci-info';
-export class LifecycleCommand {
-    command = [
+import { lifecycleInternal } from '../lifecycle/lifecycle-internal.js';
+export const lifecycleCommand = {
+    command: [
         '$0',
         'lifecycle'
-    ];
-    describe = 'Inject Nx targets as high level workflows';
-    #getProjectGraph;
-    #workspaceRoot;
-    #lifecycleInternal;
-    constructor(getProjectGraph, workspaceRoot, lifecycleInternal){
-        this.#getProjectGraph = getProjectGraph;
-        this.#workspaceRoot = workspaceRoot;
-        this.#lifecycleInternal = lifecycleInternal;
-        this.handler = this.handler.bind(this);
-    }
-    builder(yargs) {
-        return yargs.options({
+    ],
+    describe: 'Inject Nx targets as high level workflows',
+    builder: (yargs)=>yargs.options({
             configFile: {
                 describe: 'File that exports data content to populate',
                 type: 'string',
@@ -32,23 +24,22 @@ export class LifecycleCommand {
                 type: 'boolean',
                 default: false
             }
-        }).strict();
-    }
-    async handler(options) {
-        const projectGraph = await this.#getProjectGraph();
-        await this.#lifecycleInternal({
+        }).strict(),
+    handler: async (options)=>{
+        const projectGraph = await createProjectGraphAsync();
+        await lifecycleInternal({
             configFile: options.configFile,
             cwd: options.cwd,
             check: options.ci,
             dryRun: options.dryRun
         }, {
-            root: this.#workspaceRoot,
+            root: workspaceRoot,
             projects: Object.values(projectGraph.nodes).map((node)=>({
                     name: node.name,
                     root: node.data.root
                 }))
         });
     }
-}
+};
 
 //# sourceMappingURL=lifecycle-command.js.map

package/dist/executors/lifecycle/index.d.ts

@@ -1,5 +1,2 @@
-declare const _default: (options: import("../../lifecycle/schema.js").LifecycleOptionsOrConfig, context: import("./lifecycle.js").SimpleExecutorContext) => Promise<{
-    success: boolean;
-}>;
-export default _default;
+export { lifecycle as default } from './lifecycle.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/executors/lifecycle/index.js

@@ -1,6 +1,3 @@
-import { lifecycleContainer } from './container.js';
-import { Lifecycle } from './lifecycle.js';
-const lifecycle = lifecycleContainer.get(Lifecycle);
-export default lifecycle.lifecycle;
+export { lifecycle as default } from './lifecycle.js';
 
 //# sourceMappingURL=index.js.map

package/dist/executors/lifecycle/lifecycle.d.ts

@@ -1,19 +1,18 @@
 import type { ExecutorContext } from '@nx/devkit';
-import type { ILifecycleInternal } from '../../lifecycle/lifecycle-internal.js';
 import type { LifecycleOptionsOrConfig } from '../../lifecycle/schema.js';
 export type SimpleExecutorContext = Pick<ExecutorContext, 'projectsConfigurations' | 'root'>;
 /**
- * Main logic for lifecycle file management.
+ * Nx executor for lifecycle file management.
  *
  * Loads the `nx.json` + `project.json`s for all projects,
  * calculates the new targets and dependencies,
  * and re-writes files as appropriate.
+ *
+ * @param options - options provided directly, or where to load them from
+ * @param context - Nx executor context
+ * @returns success, as failures throw
  */
-export declare class Lifecycle {
-    #private;
-    readonly lifecycle: (options: LifecycleOptionsOrConfig, context: SimpleExecutorContext) => Promise<{
-        success: boolean;
-    }>;
-    constructor(lifecycleInternal: ILifecycleInternal);
-}
+export declare const lifecycle: (options: LifecycleOptionsOrConfig, context: SimpleExecutorContext) => Promise<{
+    success: boolean;
+}>;
 //# sourceMappingURL=lifecycle.d.ts.map

package/dist/executors/lifecycle/lifecycle.js

@@ -1,22 +1,15 @@
-export class Lifecycle {
-    #lifecycleInternal;
-    lifecycle;
-    constructor(lifecycleInternal){
-        this.#lifecycleInternal = lifecycleInternal;
-        this.lifecycle = this.#lifecycle.bind(this);
-    }
-    async #lifecycle(options, context) {
-        await this.#lifecycleInternal(options, {
-            root: context.root,
-            projects: Object.values(context.projectsConfigurations.projects).map((projectConfig)=>({
-                    name: projectConfig.name,
-                    root: projectConfig.root
-                }))
-        });
-        return {
-            success: true
-        };
-    }
-}
+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
+            }))
+    });
+    return {
+        success: true
+    };
+};
 
 //# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle/explain.d.ts

@@ -0,0 +1,68 @@
+import type { ProjectGraph } from '@nx/devkit';
+import type { LifecyclePlan } from './processor.js';
+export interface DependencyExplanation {
+    /**
+     * Dependency as written, e.g. `prepare`, `^build` or `my-server:build`.
+     */
+    label: string;
+    /**
+     * For a `^` dependency, the upstream projects it runs the target of.
+     */
+    upstream?: readonly string[];
+}
+export interface BoundTargetExplanation {
+    name: string;
+    /**
+     * Dependencies besides the hook the target is bound after.
+     */
+    dependsOn: readonly DependencyExplanation[];
+}
+export interface HookExplanation {
+    name: string;
+    targets: readonly BoundTargetExplanation[];
+}
+export interface StageExplanation {
+    name: string;
+    dependsOn: readonly DependencyExplanation[];
+    /**
+     * Hooks in order. A stage without hooks has a single entry, the stage itself.
+     */
+    hooks: readonly HookExplanation[];
+    hasHooks: boolean;
+}
+export interface LifecycleExplanation {
+    project: string;
+    /**
+     * Stages in the order they run, each after the stages it depends on.
+     */
+    stages: readonly StageExplanation[];
+}
+/**
+ * Describes what runs, and in which order, for the stages of one project.
+ *
+ * Stage dependencies come from the lifecycle configuration.
+ * Bound targets, and their other dependencies, come from the merged project configuration,
+ * so they match what Nx runs.
+ *
+ * @param params - required
+ * @param params.plan - lifecycle targets and bindings
+ * @param params.graph - project graph, with merged project configurations
+ * @param params.project - name of the project to explain
+ * @param [params.stage] - only explain this stage, and the stages it runs after
+ * @returns stages in run order
+ * @throws {Error} when the project or stage does not exist
+ */
+export declare const explainLifecycle: ({ plan, graph, project, stage, }: {
+    plan: LifecyclePlan;
+    graph: ProjectGraph;
+    project: string;
+    stage?: string;
+}) => LifecycleExplanation;
+/**
+ * Prints an explanation as an indented outline.
+ *
+ * @param explanation - stages of a project
+ * @returns human readable outline
+ */
+export declare const formatExplanation: ({ project, stages }: LifecycleExplanation) => string;
+//# sourceMappingURL=explain.d.ts.map

package/dist/lifecycle/explain.js

@@ -0,0 +1,160 @@
+const normalizeDependency = (dependency)=>{
+    if (typeof dependency !== 'string') {
+        return dependency;
+    }
+    if (dependency.startsWith('^')) {
+        return {
+            target: dependency.slice(1),
+            dependencies: true
+        };
+    }
+    return {
+        target: dependency
+    };
+};
+const resolveUpstream = (graph, projectName, target)=>{
+    const upstream = new Set();
+    const visited = new Set([
+        projectName
+    ]);
+    const visit = (name)=>{
+        for (const dependency of graph.dependencies[name] ?? []){
+            const node = graph.nodes[dependency.target];
+            if (!node || visited.has(dependency.target)) {
+                continue;
+            }
+            visited.add(dependency.target);
+            if (node.data.targets && target in node.data.targets) {
+                upstream.add(dependency.target);
+            } else {
+                visit(dependency.target);
+            }
+        }
+    };
+    visit(projectName);
+    return [
+        ...upstream
+    ];
+};
+const explainDependency = (graph, projectName, dependency)=>{
+    const { target, dependencies, projects } = normalizeDependency(dependency);
+    if (dependencies) {
+        return {
+            label: `^${target}`,
+            upstream: resolveUpstream(graph, projectName, target)
+        };
+    }
+    if (projects !== undefined) {
+        return {
+            label: [
+                projects
+            ].flat().map((project)=>`${project}:${target}`).join(', ')
+        };
+    }
+    return {
+        label: target
+    };
+};
+const orderStages = (plan, stageDependencies, stage)=>{
+    const ordered = [];
+    const visited = new Set();
+    const visit = (name)=>{
+        if (visited.has(name)) {
+            return;
+        }
+        visited.add(name);
+        for (const dependency of stageDependencies.get(name)){
+            visit(dependency);
+        }
+        ordered.push(name);
+    };
+    if (stage === undefined) {
+        for (const [name, target] of plan.lifecycleTargets){
+            if (target.kind === 'base') {
+                visit(name);
+            }
+        }
+    } else {
+        visit(stage);
+    }
+    return ordered;
+};
+export const explainLifecycle = ({ plan, graph, project, stage })=>{
+    const node = graph.nodes[project];
+    if (!node) {
+        throw new Error(`Project ${project} not found`);
+    }
+    const targets = node.data.targets ?? {};
+    const stageNames = [
+        ...plan.lifecycleTargets.values()
+    ].filter((target)=>target.kind === 'base').map((target)=>target.name);
+    if (stage !== undefined && !stageNames.includes(stage)) {
+        throw new Error(`Stage ${stage} not found. Stages: ${stageNames.join(', ')}`);
+    }
+    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));
+    }
+    const explainTarget = (targetName, previousHook)=>({
+            name: targetName,
+            dependsOn: (targets[targetName]?.dependsOn ?? []).filter((dependency)=>{
+                const normalized = normalizeDependency(dependency);
+                return normalized.target !== previousHook || normalized.dependencies !== undefined || normalized.projects !== undefined;
+            }).map((dependency)=>explainDependency(graph, project, dependency))
+        });
+    const stages = orderStages(plan, stageDependencies, stage).map((stageName)=>{
+        const base = plan.lifecycleTargets.get(stageName);
+        const anchor = plan.lifecycleTargets.get(`${stageName}:_`);
+        const hookTargets = [
+            ...plan.lifecycleTargets.values()
+        ].filter((target)=>target.stage === stageName && (target.kind === 'hook' || target.kind === 'base' && !target.hasHooks));
+        return {
+            name: stageName,
+            dependsOn: anchor.dependsOn.map((dependency)=>explainDependency(graph, project, dependency)),
+            hooks: hookTargets.map((hook)=>({
+                    name: hook.name,
+                    targets: [
+                        ...plan.registeredTargets
+                    ].filter(([targetName, lifecycleTarget])=>lifecycleTarget.name === hook.name && targetName in targets).map(([targetName, lifecycleTarget])=>explainTarget(targetName, lifecycleTarget.previousHook))
+                })),
+            hasHooks: base.kind === 'base' && base.hasHooks
+        };
+    });
+    return {
+        project,
+        stages
+    };
+};
+const formatDependencies = (dependencies)=>dependencies.map(({ label, upstream })=>{
+        if (!upstream) {
+            return label;
+        }
+        return `${label} (${upstream.length > 0 ? upstream.join(', ') : 'no upstream projects'})`;
+    }).join('; ');
+const STAGE_INDENT = ' '.repeat('1. '.length);
+const HOOK_TARGET_INDENT = `${STAGE_INDENT}  `;
+export const formatExplanation = ({ project, stages })=>{
+    const lines = [
+        project
+    ];
+    for (const [index, stage] of stages.entries()){
+        lines.push('', `${index + 1}. ${stage.name}`);
+        if (stage.dependsOn.length > 0) {
+            lines.push(`${STAGE_INDENT}after: ${formatDependencies(stage.dependsOn)}`);
+        }
+        for (const hook of stage.hooks){
+            const indent = stage.hasHooks ? HOOK_TARGET_INDENT : STAGE_INDENT;
+            if (stage.hasHooks) {
+                lines.push(`${STAGE_INDENT}${hook.name}${hook.targets.length > 0 ? '' : ' (nothing bound)'}`);
+            }
+            for (const target of hook.targets){
+                const after = target.dependsOn.length > 0 ? ` (also after: ${formatDependencies(target.dependsOn)})` : '';
+                lines.push(`${indent}${target.name}${after}`);
+            }
+        }
+    }
+    return lines.join('\n');
+};
+
+//# sourceMappingURL=explain.js.map

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

@@ -1,22 +1,14 @@
-import type { readFile as ReadFile, writeFile as WriteFile } from 'node:fs/promises';
-import type { FilesFormatter } from 'format-file';
-import type { AssertNxJson, AssertProjectJson } from '#schemas';
-import type { Logger } from './dependencies.js';
-import type { Normalizer } from './normalizer.js';
-import type { NxAndProjectJsonProcessor } from './processor.js';
 import type { LifecycleOptionsOrConfig } from './schema.js';
 import type { NxContext } from './types.js';
-export type ILifecycleInternal = (options: LifecycleOptionsOrConfig, context: NxContext) => Promise<void>;
 /**
  * Main logic for lifecycle file management.
  *
  * Loads the `nx.json` + `project.json`s for all projects,
  * calculates the new targets and dependencies,
  * and re-writes files as appropriate.
+ *
+ * @param options - options provided directly, or where to load them from
+ * @param context - workspace root and projects
  */
-export declare class LifecycleInternal {
-    #private;
-    readonly lifecycleInternal: ILifecycleInternal;
-    constructor(normalizer: Normalizer, readFile: typeof ReadFile, writeFile: typeof WriteFile, formatFiles: FilesFormatter, processNxAndProjectJsons: NxAndProjectJsonProcessor, assertNxJson: AssertNxJson, assertProjectJson: AssertProjectJson, logger: Logger);
-}
+export declare const lifecycleInternal: (options: LifecycleOptionsOrConfig, context: NxContext) => Promise<void>;
 //# sourceMappingURL=lifecycle-internal.d.ts.map