@storm-software/workspace-tools 1.269.0 → 1.270.0

package/generators.ts

@@ -0,0 +1,14 @@
+export * from "./src/generators/browser-library/generator";
+export { type BrowserLibraryGeneratorSchema } from "./src/generators/browser-library/schema.d";
+export * from "./src/generators/config-schema/generator";
+export { type ConfigSchemaGeneratorSchema } from "./src/generators/config-schema/schema.d";
+export * from "./src/generators/init/init";
+export { type InitGeneratorSchema } from "./src/generators/init/schema.d";
+export * from "./src/generators/neutral-library/generator";
+export { type NeutralLibraryGeneratorSchema } from "./src/generators/neutral-library/schema.d";
+export * from "./src/generators/node-library/generator";
+export { type NodeLibraryGeneratorSchema } from "./src/generators/node-library/schema.d";
+export * from "./src/generators/preset/generator";
+export { type PresetGeneratorSchema } from "./src/generators/preset/schema.d";
+export * from "./src/generators/release-version/generator";
+export { type ReleaseVersionGeneratorSchema } from "./src/generators/release-version/schema.d";

package/index.ts

@@ -0,0 +1,5 @@
+export * from "./executors";
+export * from "./generators";
+export * from "./src/base";
+export * from "./src/types";
+export * from "./src/utils";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storm-software/workspace-tools",
-  "version": "1.269.0",
+  "version": "1.270.0",
   "description": "Tools for managing a Storm workspace, including various Nx generators and executors for common development tasks.",
   "repository": {
     "type": "github",
@@ -226,9 +226,9 @@
     "@size-limit/esbuild": "11.1.4",
     "@size-limit/esbuild-why": "11.1.4",
     "@size-limit/file": "11.1.4",
-    "@storm-software/esbuild": "0.37.0",
-    "@storm-software/prettier": "0.47.0",
-    "@storm-software/unbuild": "0.43.0",
+    "@storm-software/esbuild": "0.38.0",
+    "@storm-software/prettier": "0.48.0",
+    "@storm-software/unbuild": "0.44.0",
     "fs-extra": "11.2.0",
     "glob": "^11.0.1",
     "jiti": "^2.4.2",

package/project.json

@@ -0,0 +1,58 @@
+{
+  "name": "workspace-tools",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/workspace-tools/src",
+  "projectType": "library",
+  "implicitDependencies": ["untyped", "unbuild", "esbuild"],
+  "targets": {
+    "build-untyped": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["clean", "^build"],
+      "inputs": [
+        "{projectRoot}/src/**/untyped.ts",
+        "{projectRoot}/src/**/*.untyped.ts"
+      ],
+      "outputs": [
+        "{projectRoot}/src/**/schema.d.ts",
+        "{projectRoot}/src/**/*.schema.d.ts",
+        "{projectRoot}/src/**/schema.md",
+        "{projectRoot}/src/**/*.schema.md",
+        "{projectRoot}/src/**/schema.json",
+        "{projectRoot}/src/**/*.schema.json"
+      ],
+      "options": {
+        "commands": [
+          "node dist/packages/untyped/bin/untyped.cjs generate --entry=\"packages/workspace-tools/**/{untyped.ts,*.untyped.ts}\" "
+        ]
+      }
+    },
+    "build-base": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["clean", "build-untyped", "^build"],
+      "options": {
+        "command": "tsup-node --config=tsup.config.ts",
+        "cwd": "{projectRoot}"
+      }
+    },
+    "build": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build-base", "build-untyped"],
+      "options": {
+        "commands": [
+          "pnpm copyfiles LICENSE dist/packages/workspace-tools",
+          "pnpm copyfiles --up=2 ./packages/workspace-tools/*.md ./packages/workspace-tools/executors.json ./packages/workspace-tools/generators.json ./packages/workspace-tools/package.json dist/packages/workspace-tools",
+          "pnpm copyfiles --up=3 ./packages/workspace-tools/assets/* dist/packages/workspace-tools/assets",
+          "pnpm copyfiles --up=3 ./packages/workspace-tools/config/* dist/packages/workspace-tools/config",
+          "pnpm copyfiles --up=3 ./packages/workspace-tools/docs/* dist/packages/workspace-tools/docs",
+          "pnpm copyfiles --up=3 \"./packages/workspace-tools/src/**/*schema.*\" dist/packages/workspace-tools/dist/src",
+          "pnpm copyfiles --up=3 \"./packages/workspace-tools/src/**/*.md\" dist/packages/workspace-tools/docs/api",
+          "pnpm copyfiles --up=4 \"./packages/workspace-tools/src/generators/*/files/**/*\" dist/packages/workspace-tools/dist/src/generators",
+          "pnpm copyfiles --up=3 \"./packages/workspace-tools/dist/**/*\" dist/packages/workspace-tools/dist"
+        ]
+      }
+    },
+    "nx-release-publish": {
+      "executor": "@storm-software/workspace-tools:npm-publish"
+    }
+  }
+}

package/src/base/base-executor.ts

@@ -0,0 +1,200 @@
+import type { ExecutorContext, PromiseExecutor } from "@nx/devkit";
+import type { StormWorkspaceConfig } from "@storm-software/config";
+import {
+  applyWorkspaceProjectTokens,
+  applyWorkspaceTokens,
+  findWorkspaceRoot,
+  formatLogMessage,
+  getConfig,
+  getStopwatch,
+  ProjectTokenizerOptions,
+  writeDebug,
+  writeError,
+  writeFatal,
+  writeInfo,
+  writeSuccess,
+  writeTrace
+} from "@storm-software/config-tools";
+import { defu } from "defu";
+import { BaseExecutorOptions, BaseExecutorResult } from "../types";
+import { BaseExecutorSchema } from "./base-executor.schema.d";
+
+export const withRunExecutor =
+  <TExecutorSchema extends BaseExecutorSchema = BaseExecutorSchema>(
+    name: string,
+    executorFn: (
+      options: TExecutorSchema,
+      context: ExecutorContext,
+      config: StormWorkspaceConfig
+    ) =>
+      | Promise<BaseExecutorResult | null | undefined>
+      | AsyncGenerator<any, BaseExecutorResult | null | undefined>
+      | BaseExecutorResult
+      | null
+      | undefined,
+    executorOptions: BaseExecutorOptions<TExecutorSchema> = {}
+  ): PromiseExecutor<TExecutorSchema> =>
+  async (
+    _options: TExecutorSchema,
+    context: ExecutorContext
+  ): Promise<{ success: boolean }> => {
+    const stopwatch = getStopwatch(name);
+    let options = _options;
+
+    let config = {} as StormWorkspaceConfig;
+    try {
+      if (
+        !context.projectsConfigurations?.projects ||
+        !context.projectName ||
+        !context.projectsConfigurations.projects[context.projectName]
+      ) {
+        throw new Error(
+          "The Build process failed because the context is not valid. Please run this command from a workspace."
+        );
+      }
+
+      const workspaceRoot = findWorkspaceRoot();
+      const projectRoot =
+        context.projectsConfigurations.projects[context.projectName]!.root ||
+        workspaceRoot;
+      const sourceRoot =
+        context.projectsConfigurations.projects[context.projectName]!
+          .sourceRoot ||
+        projectRoot ||
+        workspaceRoot;
+      const projectName = context.projectName;
+      config.workspaceRoot = workspaceRoot;
+
+      writeInfo(`⚡ Running the ${name} executor for ${projectName} `, config);
+
+      if (!executorOptions.skipReadingConfig) {
+        writeTrace(
+          `Loading the Storm Config from environment variables and storm.config.js file...
+ - workspaceRoot: ${workspaceRoot}
+ - projectRoot: ${projectRoot}
+ - sourceRoot: ${sourceRoot}
+ - projectName: ${projectName}\n`,
+          config
+        );
+
+        config = await getConfig(workspaceRoot);
+      }
+
+      if (executorOptions?.hooks?.applyDefaultOptions) {
+        writeDebug("Running the applyDefaultOptions hook...", config);
+        options = await Promise.resolve(
+          executorOptions.hooks.applyDefaultOptions(options, config)
+        );
+        writeDebug("Completed the applyDefaultOptions hook", config);
+      }
+
+      writeTrace(
+        `Executor schema options ⚙️
+${formatLogMessage(options)}
+`,
+        config
+      );
+
+      const tokenized = (await applyWorkspaceTokens<ProjectTokenizerOptions>(
+        options,
+        defu(
+          { workspaceRoot, projectRoot, sourceRoot, projectName, config },
+          config,
+          context.projectsConfigurations.projects[context.projectName]
+        ),
+        applyWorkspaceProjectTokens
+      )) as TExecutorSchema;
+
+      writeTrace(
+        `Executor schema tokenized options ⚙️
+${formatLogMessage(tokenized)}
+`,
+        config
+      );
+
+      if (executorOptions?.hooks?.preProcess) {
+        writeDebug("Running the preProcess hook...", config);
+        await Promise.resolve(
+          executorOptions.hooks.preProcess(tokenized, config)
+        );
+        writeDebug("Completed the preProcess hook", config);
+      }
+
+      const ret = executorFn(tokenized, context, config);
+      if (_isFunction((ret as AsyncGenerator)?.next)) {
+        const asyncGen = ret as AsyncGenerator;
+        for await (const iter of asyncGen) {
+          void iter;
+        }
+      }
+
+      const result = await Promise.resolve(
+        ret as
+          | Promise<BaseExecutorResult | null | undefined>
+          | BaseExecutorResult
+          | null
+          | undefined
+      );
+      if (
+        result &&
+        (!result.success ||
+          (result.error &&
+            (result?.error as Error)?.message &&
+            typeof (result?.error as Error)?.message === "string" &&
+            (result?.error as Error)?.name &&
+            typeof (result?.error as Error)?.name === "string"))
+      ) {
+        writeTrace(
+          `Failure determined by the ${name} executor \n${formatLogMessage(result)}`,
+          config
+        );
+        console.error(result);
+
+        throw new Error(`The ${name} executor failed to run`, {
+          cause: result?.error
+        });
+      }
+
+      if (executorOptions?.hooks?.postProcess) {
+        writeDebug("Running the postProcess hook...", config);
+        await Promise.resolve(executorOptions.hooks.postProcess(config));
+        writeDebug("Completed the postProcess hook", config);
+      }
+
+      writeSuccess(`Completed running the ${name} task executor!\n`, config);
+
+      return {
+        success: true
+      };
+    } catch (error) {
+      writeFatal(
+        "A fatal error occurred while running the executor - the process was forced to terminate",
+        config
+      );
+      writeError(
+        `An exception was thrown in the executor's process \n - Details: ${error.message}\n - Stacktrace: ${error.stack}`,
+        config
+      );
+
+      return {
+        success: false
+      };
+    } finally {
+      stopwatch();
+    }
+  };
+
+const _isFunction = (
+  value: unknown
+): value is ((params?: unknown) => unknown) & ((param?: any) => any) => {
+  try {
+    return (
+      value instanceof Function ||
+      typeof value === "function" ||
+      !!(value?.constructor && (value as any)?.call && (value as any)?.apply)
+    );
+    // biome-ignore lint/correctness/noUnusedVariables: <explanation>
+  } catch (e) {
+    return false;
+  }
+};

package/src/base/base-executor.untyped.ts

@@ -0,0 +1,18 @@
+import { defineUntypedSchema } from "untyped";
+
+export default defineUntypedSchema({
+  $schema: {
+    id: "baseExecutor",
+    title: "Base Executor",
+    description: "A base type definition for an executor schema",
+  },
+  outputPath: {
+    $schema: {
+      title: "Output Path",
+      type: "string",
+      format: "path",
+      description: "The output path for the build",
+    },
+    $default: "dist/{projectRoot}",
+  },
+});

package/src/base/base-generator.ts

@@ -0,0 +1,130 @@
+import type { GeneratorCallback, Tree } from "@nx/devkit";
+import type { StormWorkspaceConfig } from "@storm-software/config";
+import {
+  applyWorkspaceBaseTokens,
+  applyWorkspaceTokens,
+  findWorkspaceRoot,
+  getConfig,
+  getStopwatch,
+  writeDebug,
+  writeError,
+  writeFatal,
+  writeInfo,
+  writeSuccess,
+  writeTrace
+} from "@storm-software/config-tools";
+import type { BaseGeneratorOptions, BaseGeneratorResult } from "../types";
+import type { BaseGeneratorSchema } from "./base-generator.schema.d";
+
+export const withRunGenerator =
+  <TGeneratorSchema extends BaseGeneratorSchema = BaseGeneratorSchema>(
+    name: string,
+    generatorFn: (
+      tree: Tree,
+      options: TGeneratorSchema,
+      config?: StormWorkspaceConfig
+    ) =>
+      | Promise<BaseGeneratorResult | null | undefined>
+      | BaseGeneratorResult
+      | null
+      | undefined,
+    generatorOptions: BaseGeneratorOptions<TGeneratorSchema> = {
+      skipReadingConfig: false
+    }
+  ) =>
+  async (
+    tree: Tree,
+    _options: TGeneratorSchema
+  ): Promise<GeneratorCallback | BaseGeneratorResult> => {
+    const stopwatch = getStopwatch(name);
+    let options = _options;
+
+    let config: StormWorkspaceConfig | undefined;
+    try {
+      writeInfo(`⚡ Running the ${name} generator...\n\n`, config);
+
+      const workspaceRoot = findWorkspaceRoot();
+      if (!generatorOptions.skipReadingConfig) {
+        writeDebug(
+          `Loading the Storm Config from environment variables and storm.config.js file...
+ - workspaceRoot: ${workspaceRoot}`,
+          config
+        );
+
+        config = await getConfig(workspaceRoot);
+      }
+
+      if (generatorOptions?.hooks?.applyDefaultOptions) {
+        writeDebug("Running the applyDefaultOptions hook...", config);
+        options = await Promise.resolve(
+          generatorOptions.hooks.applyDefaultOptions(options, config)
+        );
+        writeDebug("Completed the applyDefaultOptions hook", config);
+      }
+
+      writeTrace(
+        `Generator schema options ⚙️ \n${Object.keys(options ?? {})
+          .map(key => ` - ${key}=${JSON.stringify(options[key])}`)
+          .join("\n")}`,
+        config
+      );
+
+      const tokenized = (await applyWorkspaceTokens(
+        options as Record<string, any>,
+        { workspaceRoot: tree.root, config },
+        applyWorkspaceBaseTokens
+      )) as TGeneratorSchema;
+
+      if (generatorOptions?.hooks?.preProcess) {
+        writeDebug("Running the preProcess hook...", config);
+        await Promise.resolve(
+          generatorOptions.hooks.preProcess(tokenized, config)
+        );
+        writeDebug("Completed the preProcess hook", config);
+      }
+
+      // Run the generator function
+      const result = await Promise.resolve(
+        generatorFn(tree, tokenized, config)
+      );
+      if (result) {
+        if (
+          result.success === false ||
+          (result.error &&
+            (result?.error as Error)?.message &&
+            typeof (result?.error as Error)?.message === "string" &&
+            (result?.error as Error)?.name &&
+            typeof (result?.error as Error)?.name === "string")
+        ) {
+          throw new Error(`The ${name} generator failed to run`, {
+            cause: result?.error
+          });
+        } else if (result.success && result.data) {
+          return result as any;
+        }
+      }
+
+      if (generatorOptions?.hooks?.postProcess) {
+        writeDebug("Running the postProcess hook...", config);
+        await Promise.resolve(generatorOptions.hooks.postProcess(config));
+        writeDebug("Completed the postProcess hook", config);
+      }
+
+      return () => {
+        writeSuccess(`Completed running the ${name} generator!\n`, config);
+      };
+    } catch (error) {
+      return () => {
+        writeFatal(
+          "A fatal error occurred while running the generator - the process was forced to terminate",
+          config
+        );
+        writeError(
+          `An exception was thrown in the generator's process \n - Details: ${error.message}\n - Stacktrace: ${error.stack}`,
+          config
+        );
+      };
+    } finally {
+      stopwatch();
+    }
+  };

package/src/base/base-generator.untyped.ts

@@ -0,0 +1,16 @@
+import { defineUntypedSchema } from "untyped";
+
+export default defineUntypedSchema({
+  $schema: {
+    id: "BaseGeneratorSchema",
+    title: "Base Generator",
+    description: "A type definition for the base Generator schema",
+  },
+  directory: {
+    $schema: {
+      title: "Directory",
+      type: "string",
+      description: "The directory to create the library in",
+    },
+  },
+});

package/src/base/cargo-base-executor.untyped.ts

@@ -0,0 +1,73 @@
+import { defineUntypedSchema } from "untyped";
+import baseExecutorSchema from "./base-executor.untyped";
+
+export default defineUntypedSchema({
+  ...baseExecutorSchema,
+  $schema: {
+    id: "cargoBaseExecutor",
+    title: "Cargo Base Executor",
+    description:
+      "A base type definition for a Cargo/rust related executor schema",
+  },
+  package: {
+    $schema: {
+      title: "Cargo.toml Path",
+      type: "string",
+      format: "path",
+      description: "The path to the Cargo.toml file",
+    },
+    $default: "{projectRoot}/Cargo.toml",
+  },
+  toolchain: {
+    $schema: {
+      title: "Toolchain",
+      description: "The type of toolchain to use for the build",
+      enum: ["stable", "beta", "nightly"],
+      default: "stable",
+    },
+    $default: "stable",
+  },
+  target: {
+    $schema: {
+      title: "Target",
+      type: "string",
+      description: "The target to build",
+    },
+  },
+  allTargets: {
+    $schema: {
+      title: "All Targets",
+      type: "boolean",
+      description: "Build all targets",
+    },
+  },
+  profile: {
+    $schema: {
+      title: "Profile",
+      type: "string",
+      description: "The profile to build",
+    },
+  },
+  release: {
+    $schema: {
+      title: "Release",
+      type: "boolean",
+      description: "Build in release mode",
+    },
+  },
+  features: {
+    $schema: {
+      title: "Features",
+      type: "string",
+      description: "The features to build",
+      oneOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+    },
+  },
+  allFeatures: {
+    $schema: {
+      title: "All Features",
+      type: "boolean",
+      description: "Build all features",
+    },
+  },
+});

package/src/base/index.ts

@@ -0,0 +1,8 @@
+export * from "./base-executor";
+export { default as baseExecutorSchema } from "./base-executor.untyped";
+export * from "./base-generator";
+export { default as baseGeneratorSchema } from "./base-generator.untyped";
+export { default as cargoBaseExecutorSchema } from "./cargo-base-executor.untyped";
+export { default as typescriptBuildExecutorSchema } from "./typescript-build-executor.untyped";
+export * from "./typescript-library-generator";
+export { default as typescriptLibraryGeneratorSchema } from "./typescript-library-generator.untyped";