mike-kno-9713-cli-add-reusable-step-marhsal-logic

Author: MikeCarbone

src/lib/marshal/index.isomorphic.ts

@@ -5,5 +5,6 @@ export { buildEmailLayoutDirBundle } from "./email-layout/processor.isomorphic";
 export { buildGuideDirBundle } from "./guide/processor.isomorphic";
 export { buildMessageTypeDirBundle } from "./message-type/processor.isomorphic";
 export { buildPartialDirBundle } from "./partial/processor.isomorphic";
+export { buildReusableStepDirBundle } from "./reusable-step/processor.isomorphic";
 export { buildTranslationDirBundle } from "./translation/processor.isomorphic";
 export { buildWorkflowDirBundle } from "./workflow/processor.isomorphic";

src/lib/marshal/reusable-step/helpers.ts

@@ -0,0 +1,129 @@
+import * as path from "node:path";
+
+import { ux } from "@oclif/core";
+import * as fs from "fs-extra";
+
+import { DirContext } from "@/lib/helpers/fs";
+import { ReusableStepDirContext, RunContext } from "@/lib/run-context";
+
+import { REUSABLE_STEP_JSON } from "./processor.isomorphic";
+
+export const reusableStepJsonPath = (
+  reusableStepDirCtx: ReusableStepDirContext,
+): string => path.resolve(reusableStepDirCtx.abspath, REUSABLE_STEP_JSON);
+
+/*
+ * Evaluates whether the given directory path is a reusable step directory, by
+ * checking for the presence of a `reusable-step.json` file.
+ */
+export const isReusableStepDir = async (dirPath: string): Promise<boolean> =>
+  Boolean(await lsReusableStepJson(dirPath));
+
+/*
+ * Check for `reusable-step.json` file and return the file path if present.
+ */
+export const lsReusableStepJson = async (
+  dirPath: string,
+): Promise<string | undefined> => {
+  const reusableStepJsonPath = path.resolve(dirPath, REUSABLE_STEP_JSON);
+
+  const exists = await fs.pathExists(reusableStepJsonPath);
+  return exists ? reusableStepJsonPath : undefined;
+};
+
+/*
+ * Validate the provided args and flags with the current run context, to first
+ * ensure the invoked command makes sense, and return the target context.
+ */
+type CommandTargetProps = {
+  flags: {
+    all: boolean | undefined;
+    "reusable-steps-dir": DirContext | undefined;
+  };
+  args: {
+    reusableStepKey: string | undefined;
+  };
+};
+
+type ReusableStepDirTarget = {
+  type: "reusableStepDir";
+  context: ReusableStepDirContext;
+};
+
+type ReusableStepsIndexDirTarget = {
+  type: "reusableStepsIndexDir";
+  context: DirContext;
+};
+
+export type ReusableStepCommandTarget =
+  | ReusableStepDirTarget
+  | ReusableStepsIndexDirTarget;
+
+export const ensureValidCommandTarget = async (
+  props: CommandTargetProps,
+  runContext: RunContext,
+): Promise<ReusableStepCommandTarget> => {
+  const { args, flags } = props;
+  const { commandId, resourceDir: resourceDirCtx, cwd: runCwd } = runContext;
+
+  // If the target resource is a different type than the current resource dir
+  // type, error out.
+  if (resourceDirCtx && resourceDirCtx.type !== "reusable_step") {
+    return ux.error(
+      `Cannot run ${commandId} inside a ${resourceDirCtx.type} directory`,
+    );
+  }
+
+  // Cannot accept both reusable step key arg and --all flag.
+  if (flags.all && args.reusableStepKey) {
+    return ux.error(
+      `reusableStepKey arg \`${args.reusableStepKey}\` cannot also be provided when using --all`,
+    );
+  }
+
+  // --all flag is given, which means no reusable step key arg.
+  if (flags.all) {
+    // If --all flag used inside a reusable step directory, then require a reusable steps
+    // dir path.
+    if (resourceDirCtx && !flags["reusable-steps-dir"]) {
+      return ux.error("Missing required flag reusable-steps-dir");
+    }
+
+    // Targeting all reusable step dirs in the reusable steps index dir.
+    // TODO: Default to the knock project config first if present before cwd.
+    const defaultToCwd = { abspath: runCwd, exists: true };
+    const indexDirCtx = flags["reusable-steps-dir"] || defaultToCwd;
+
+    return { type: "reusableStepsIndexDir", context: indexDirCtx };
+  }
+
+  // Reusable step key arg is given, which means no --all flag.
+  if (args.reusableStepKey) {
+    if (resourceDirCtx && resourceDirCtx.key !== args.reusableStepKey) {
+      return ux.error(
+        `Cannot run ${commandId} \`${args.reusableStepKey}\` inside another reusable step directory:\n${resourceDirCtx.key}`,
+      );
+    }
+
+    const targetDirPath = resourceDirCtx
+      ? resourceDirCtx.abspath
+      : path.resolve(runCwd, args.reusableStepKey);
+
+    const reusableStepDirCtx: ReusableStepDirContext = {
+      type: "reusable_step",
+      key: args.reusableStepKey,
+      abspath: targetDirPath,
+      exists: await isReusableStepDir(targetDirPath),
+    };
+
+    return { type: "reusableStepDir", context: reusableStepDirCtx };
+  }
+
+  // From this point on, we have neither a reusable step key arg nor --all flag.
+  // If running inside a reusable step directory, then use that.
+  if (resourceDirCtx) {
+    return { type: "reusableStepDir", context: resourceDirCtx };
+  }
+
+  return ux.error("Missing 1 required arg:\nreusableStepKey");
+};

src/lib/marshal/reusable-step/index.ts

@@ -0,0 +1,5 @@
+export * from "./helpers";
+export * from "./processor.isomorphic";
+export * from "./reader";
+export * from "./types";
+export * from "./writer";

src/lib/marshal/reusable-step/processor.isomorphic.ts

@@ -0,0 +1,122 @@
+/*
+ * IMPORTANT:
+ *
+ * This file is suffixed with `.isomorphic` because the code in this file is
+ * meant to run not just in a nodejs environment but also in a browser. For this
+ * reason there are some restrictions for which nodejs imports are allowed in
+ * this module. See `.eslintrc.json` for more details.
+ */
+import { cloneDeep, get, has, set, unset } from "lodash";
+
+import { AnyObj } from "@/lib/helpers/object.isomorphic";
+import { ObjKeyOrArrayIdx, ObjPath } from "@/lib/helpers/object.isomorphic";
+import { FILEPATH_MARKER } from "@/lib/marshal/shared/const.isomorphic";
+import { ExtractionSettings, WithAnnotation } from "@/lib/marshal/shared/types";
+
+import { prepareResourceJson } from "../shared/helpers.isomorphic";
+import { ReusableStepData } from "./types";
+
+export const REUSABLE_STEP_JSON = "reusable-step.json";
+
+export type ReusableStepDirBundle = {
+  [relpath: string]: string;
+};
+
+/*
+ * Traverse a given reusable step data and compile extraction settings of every
+ * extractable field into a sorted map.
+ *
+ * NOTE: Currently we do NOT support content extraction at nested levels for
+ * reusable steps.
+ */
+type CompiledExtractionSettings = Map<ObjKeyOrArrayIdx[], ExtractionSettings>;
+
+const compileExtractionSettings = (
+  reusableStep: ReusableStepData<WithAnnotation>,
+): CompiledExtractionSettings => {
+  const extractableFields = get(
+    reusableStep,
+    ["__annotation", "extractable_fields"],
+    {},
+  );
+  const map: CompiledExtractionSettings = new Map();
+
+  for (const key of Object.keys(reusableStep)) {
+    // If the field we are on is extractable, then add its extraction
+    // settings to the map with the current object path.
+    if (key in extractableFields) {
+      map.set([key], extractableFields[key]);
+    }
+  }
+
+  return map;
+};
+
+/*
+ * For a given reusable step payload, this function builds a "reusable step
+ * directory bundle". This is an object which contains all the relative paths and
+ * its file content. It includes the extractable fields, which are extracted out
+ * and added to the bundle as separate files.
+ */
+export const buildReusableStepDirBundle = (
+  remoteReusableStep: ReusableStepData<WithAnnotation>,
+  localReusableStep: AnyObj = {},
+): ReusableStepDirBundle => {
+  const bundle: ReusableStepDirBundle = {};
+  const mutRemoteReusableStep = cloneDeep(remoteReusableStep);
+  // A map of extraction settings of every field in the reusable step
+  const compiledExtractionSettings = compileExtractionSettings(
+    mutRemoteReusableStep,
+  );
+
+  // Iterate through each extractable field, determine whether we need to
+  // extract the field content, and if so, perform the extraction.
+  for (const [objPathParts, extractionSettings] of compiledExtractionSettings) {
+    // If this reusable step doesn't have this field path, then we don't extract.
+    if (!has(mutRemoteReusableStep, objPathParts)) continue;
+
+    // If the field at this path is extracted in the local reusable step, then
+    // always extract; otherwise extract based on the field settings default.
+    const objPathStr = ObjPath.stringify(objPathParts);
+
+    const extractedFilePath = get(
+      localReusableStep,
+      `${objPathStr}${FILEPATH_MARKER}`,
+    );
+
+    const { default: extractByDefault, file_ext: fileExt } = extractionSettings;
+
+    if (!extractedFilePath && !extractByDefault) continue;
+
+    // By this point, we have a field where we need to extract its content.
+    const data = get(mutRemoteReusableStep, objPathParts);
+    const fileName = objPathParts.pop();
+
+    // If we have an extracted file path from the local reusable step, we use that.
+    // In the other case we use the default path.
+    const relpath =
+      typeof extractedFilePath === "string"
+        ? extractedFilePath
+        : `${fileName}.${fileExt}`;
+
+    // Perform the extraction by adding the content and its file path to the
+    // bundle for writing to the file system later. Then replace the field
+    // content with the extracted file path and mark the field as extracted
+    // with @ suffix.
+    const content =
+      typeof data === "string" ? data : JSON.stringify(data, null, 2);
+
+    set(bundle, [relpath], content);
+    set(mutRemoteReusableStep, `${objPathStr}${FILEPATH_MARKER}`, relpath);
+    unset(mutRemoteReusableStep, objPathStr);
+  }
+
+  // At this point the bundle contains all extractable files, so we finally add
+  // the reusable step JSON relative path + the file content.
+
+  return set(
+    bundle,
+    [REUSABLE_STEP_JSON],
+    prepareResourceJson(mutRemoteReusableStep),
+  );
+};