@ahmedrowaihi/pdf-forge-cli 1.0.0-canary.0

package/src/utils/esbuild/renderring-utilities-exporter.ts

@@ -0,0 +1,62 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { Loader, PluginBuild, ResolveOptions } from 'esbuild';
+import { escapeStringForRegex } from './escape-string-for-regex.js';
+
+/**
+ * Made to export the `render` function out of the user's PDF template
+ * so that React version mismatches don't happen.
+ *
+ * This also exports the `createElement` from the user's React version as well
+ * to avoid mismatches.
+ *
+ * This avoids multiple versions of React being involved, i.e., the version
+ * in the CLI vs. the version the user has on their templates.
+ */
+export const renderingUtilitiesExporter = (pdfTemplates: string[]) => ({
+  name: 'rendering-utilities-exporter',
+  setup: (b: PluginBuild) => {
+    b.onLoad(
+      {
+        filter: new RegExp(
+          pdfTemplates
+            .map((templatePath) => escapeStringForRegex(templatePath))
+            .join('|'),
+        ),
+      },
+      async ({ path: pathToFile }) => {
+        return {
+          contents: `${await fs.readFile(pathToFile, 'utf8')};
+          export { render } from 'react-pdf-module-that-will-export-render'
+          export { createElement as reactPDFCreateReactElement } from 'react';
+        `,
+          loader: path.extname(pathToFile).slice(1) as Loader,
+        };
+      },
+    );
+
+    b.onResolve(
+      { filter: /^react-pdf-module-that-will-export-render$/ },
+      async (args) => {
+        const options: ResolveOptions = {
+          kind: 'import-statement',
+          importer: args.importer,
+          resolveDir: args.resolveDir,
+          namespace: args.namespace,
+        };
+        let result = await b.resolve('@ahmedrowaihi/pdf-forge-core', options);
+        if (result.errors.length === 0) {
+          return result;
+        }
+
+        // If @ahmedrowaihi/pdf-forge-core does not exist, resolve to @ahmedrowaihi/pdf-forge-components
+        result = await b.resolve('@ahmedrowaihi/pdf-forge-components', options);
+        if (result.errors.length > 0 && result.errors[0]) {
+          result.errors[0].text =
+            "Failed trying to import `render` from either `@ahmedrowaihi/pdf-forge-core` or `@ahmedrowaihi/pdf-forge-components` to be able to render your PDF template.\n Maybe you don't have either of them installed?";
+        }
+        return result;
+      },
+    );
+  },
+});

package/src/utils/get-preview-server-location.ts

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { createJiti } from 'jiti';
+import { addDevDependency } from 'nypm';
+import prompts from 'prompts';
+import { packageJson } from './packageJson.js';
+
+const ensurePreviewServerInstalled = async (
+  message: string,
+): Promise<never> => {
+  const response = await prompts({
+    type: 'confirm',
+    name: 'installPreviewServer',
+    message,
+    initial: true,
+  });
+  if (response.installPreviewServer) {
+    console.log('Installing "@ahmedrowaihi/pdf-forge-preview"');
+    await addDevDependency(
+      `@ahmedrowaihi/pdf-forge-preview@${packageJson.version}`,
+    );
+    process.exit(0);
+  } else {
+    process.exit(0);
+  }
+};
+
+const findWorkspacePreviewServer = (): string | null => {
+  const cwd = process.cwd();
+
+  let workspaceRoot: string | null = null;
+  let currentPath = cwd;
+  while (currentPath !== path.dirname(currentPath)) {
+    const pnpmWorkspace = path.join(currentPath, 'pnpm-workspace.yaml');
+    if (fs.existsSync(pnpmWorkspace)) {
+      workspaceRoot = currentPath;
+      break;
+    }
+    currentPath = path.dirname(currentPath);
+  }
+
+  if (workspaceRoot) {
+    const previewServerPath = path.resolve(
+      workspaceRoot,
+      'packages/preview-server',
+    );
+    const packageJsonPath = path.join(previewServerPath, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as {
+          name: string;
+        };
+        if (pkg.name === '@ahmedrowaihi/pdf-forge-preview') {
+          return previewServerPath;
+        }
+      } catch {
+        // Invalid package.json, continue
+      }
+    }
+  }
+  return null;
+};
+
+export const getPreviewServerLocation = async () => {
+  const usersProject = createJiti(process.cwd());
+  let previewServerLocation!: string;
+
+  // First try to find it in workspace
+  const workspacePath = findWorkspacePreviewServer();
+  if (workspacePath) {
+    previewServerLocation = workspacePath;
+  } else {
+    // Try to resolve from node_modules
+    try {
+      previewServerLocation = path.dirname(
+        url.fileURLToPath(
+          usersProject.esmResolve('@ahmedrowaihi/pdf-forge-preview'),
+        ),
+      );
+    } catch {
+      await ensurePreviewServerInstalled(
+        'To run the preview server, the package "@ahmedrowaihi/pdf-forge-preview" must be installed. Would you like to install it?',
+      );
+    }
+  }
+
+  // If we found it in workspace, skip version check (workspace packages are always in sync)
+  if (!workspacePath) {
+    // Verify version if we can import it (only for non-workspace installations)
+    try {
+      const { version } = await usersProject.import<{
+        version: string;
+      }>('@ahmedrowaihi/pdf-forge-preview');
+      if (version !== packageJson.version) {
+        await ensurePreviewServerInstalled(
+          `To run the preview server, the version of "@ahmedrowaihi/pdf-forge-preview" must match the version of "@ahmedrowaihi/pdf-forge-cli" (${packageJson.version}). Would you like to install it?`,
+        );
+      }
+    } catch {
+      await ensurePreviewServerInstalled(
+        'To run the preview server, the package "@ahmedrowaihi/pdf-forge-preview" must be installed. Would you like to install it?',
+      );
+    }
+  }
+
+  return previewServerLocation;
+};

package/src/utils/get-templates-directory-metadata.ts

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const isFileATemplate = async (fullPath: string): Promise<boolean> => {
+  let fileHandle: fs.promises.FileHandle;
+  try {
+    fileHandle = await fs.promises.open(fullPath, 'r');
+  } catch (exception) {
+    console.warn(exception);
+    return false;
+  }
+  const stat = await fileHandle.stat();
+
+  if (stat.isDirectory()) {
+    await fileHandle.close();
+    return false;
+  }
+
+  const { ext } = path.parse(fullPath);
+
+  if (!['.js', '.tsx', '.jsx'].includes(ext)) {
+    await fileHandle.close();
+    return false;
+  }
+
+  // check with a heuristic to see if the file has at least
+  // a default export (ES6) or module.exports (CommonJS) or named exports (MDX)
+  const fileContents = await fileHandle.readFile('utf8');
+
+  await fileHandle.close();
+
+  // Check for ES6 export default syntax
+  const hasES6DefaultExport = /\bexport\s+default\b/gm.test(fileContents);
+
+  // Check for CommonJS module.exports syntax
+  const hasCommonJSExport = /\bmodule\.exports\s*=/gm.test(fileContents);
+
+  // Check for named exports (used in MDX files) and ensure at least one is marked as default
+  const hasNamedExport = /\bexport\s+\{[^}]*\bdefault\b[^}]*\}/gm.test(
+    fileContents,
+  );
+
+  return hasES6DefaultExport || hasCommonJSExport || hasNamedExport;
+};
+
+export interface TemplatesDirectory {
+  absolutePath: string;
+  relativePath: string;
+  directoryName: string;
+  templateFilenames: string[];
+  subDirectories: TemplatesDirectory[];
+}
+
+const mergeDirectoriesWithSubDirectories = (
+  templatesDirectoryMetadata: TemplatesDirectory,
+): TemplatesDirectory => {
+  let currentResultingMergedDirectory: TemplatesDirectory =
+    templatesDirectoryMetadata;
+
+  while (
+    currentResultingMergedDirectory.templateFilenames.length === 0 &&
+    currentResultingMergedDirectory.subDirectories.length === 1
+  ) {
+    const onlySubDirectory = currentResultingMergedDirectory.subDirectories[0]!;
+    currentResultingMergedDirectory = {
+      ...onlySubDirectory,
+      directoryName: path.join(
+        currentResultingMergedDirectory.directoryName,
+        onlySubDirectory.directoryName,
+      ),
+    };
+  }
+
+  return currentResultingMergedDirectory;
+};
+
+export const getTemplatesDirectoryMetadata = async (
+  absolutePathToTemplatesDirectory: string,
+  keepFileExtensions = false,
+  isSubDirectory = false,
+  baseDirectoryPath = absolutePathToTemplatesDirectory,
+): Promise<TemplatesDirectory | undefined> => {
+  if (!fs.existsSync(absolutePathToTemplatesDirectory)) return;
+
+  const dirents = await fs.promises.readdir(absolutePathToTemplatesDirectory, {
+    withFileTypes: true,
+  });
+
+  const isTemplatePredicates = await Promise.all(
+    dirents.map((dirent) =>
+      isFileATemplate(path.join(absolutePathToTemplatesDirectory, dirent.name)),
+    ),
+  );
+  const templateFilenames = dirents
+    .filter((_, i) => isTemplatePredicates[i])
+    .map((dirent) =>
+      keepFileExtensions
+        ? dirent.name
+        : dirent.name.replace(path.extname(dirent.name), ''),
+    );
+
+  const subDirectories = await Promise.all(
+    dirents
+      .filter(
+        (dirent) =>
+          dirent.isDirectory() &&
+          !dirent.name.startsWith('_') &&
+          dirent.name !== 'static',
+      )
+      .map((dirent) => {
+        const direntAbsolutePath = path.join(
+          absolutePathToTemplatesDirectory,
+          dirent.name,
+        );
+
+        return getTemplatesDirectoryMetadata(
+          direntAbsolutePath,
+          keepFileExtensions,
+          true,
+          baseDirectoryPath,
+        ) as Promise<TemplatesDirectory>;
+      }),
+  );
+
+  const templatesMetadata = {
+    absolutePath: absolutePathToTemplatesDirectory,
+    relativePath: path.relative(
+      baseDirectoryPath,
+      absolutePathToTemplatesDirectory,
+    ),
+    directoryName: absolutePathToTemplatesDirectory.split(path.sep).pop()!,
+    templateFilenames,
+    subDirectories,
+  } satisfies TemplatesDirectory;
+
+  return isSubDirectory
+    ? mergeDirectoriesWithSubDirectories(templatesMetadata)
+    : templatesMetadata;
+};

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export { setupHotreloading } from './preview/hot-reloading/setup-hot-reloading.js';
+export { startDevServer } from './preview/start-dev-server.js';
+export { tree } from './tree.js';

package/src/utils/packageJson.ts

@@ -0,0 +1,4 @@
+// @ts-expect-error Typescript doesn't want to allow this, but it's fine since we're using tsdown
+import packageJson from '../../package.json';
+
+export { packageJson };

package/src/utils/preview/get-env-variables-for-preview-app.ts

@@ -0,0 +1,17 @@
+import path from 'node:path';
+
+export const getEnvVariablesForPreviewApp = (
+  relativePathToTemplatesDirectory: string,
+  previewServerLocation: string,
+  cwd: string,
+) => {
+  return {
+    TEMPLATES_DIR_RELATIVE_PATH: relativePathToTemplatesDirectory,
+    TEMPLATES_DIR_ABSOLUTE_PATH: path.resolve(
+      cwd,
+      relativePathToTemplatesDirectory,
+    ),
+    PREVIEW_SERVER_LOCATION: previewServerLocation,
+    USER_PROJECT_LOCATION: cwd,
+  } as const;
+};

package/src/utils/preview/hot-reloading/create-dependency-graph.ts

@@ -0,0 +1,345 @@
+import { existsSync, promises as fs, statSync } from 'node:fs';
+import path from 'node:path';
+import type { EventName } from 'chokidar/handler.js';
+import { getImportedModules } from './get-imported-modules.js';
+import { resolvePathAliases } from './resolve-path-aliases.js';
+
+interface Module {
+  path: string;
+
+  dependencyPaths: string[];
+  dependentPaths: string[];
+
+  moduleDependencies: string[];
+}
+
+export type DependencyGraph = Record</* path to module */ string, Module>;
+
+const readAllFilesInsideDirectory = async (directory: string) => {
+  let allFilePaths: string[] = [];
+
+  const topLevelDirents = await fs.readdir(directory, { withFileTypes: true });
+
+  for (const dirent of topLevelDirents) {
+    const pathToDirent = path.join(directory, dirent.name);
+    if (dirent.isDirectory()) {
+      allFilePaths = allFilePaths.concat(
+        await readAllFilesInsideDirectory(pathToDirent),
+      );
+    } else {
+      allFilePaths.push(pathToDirent);
+    }
+  }
+
+  return allFilePaths;
+};
+
+const javascriptExtensions = ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'];
+
+const isJavascriptModule = (filePath: string) => {
+  const extensionName = path.extname(filePath);
+
+  return javascriptExtensions.includes(extensionName);
+};
+
+const checkFileExtensionsUntilItExists = (
+  pathWithoutExtension: string,
+): string | undefined => {
+  if (existsSync(`${pathWithoutExtension}.ts`)) {
+    return `${pathWithoutExtension}.ts`;
+  }
+
+  if (existsSync(`${pathWithoutExtension}.tsx`)) {
+    return `${pathWithoutExtension}.tsx`;
+  }
+
+  if (existsSync(`${pathWithoutExtension}.js`)) {
+    return `${pathWithoutExtension}.js`;
+  }
+
+  if (existsSync(`${pathWithoutExtension}.jsx`)) {
+    return `${pathWithoutExtension}.jsx`;
+  }
+
+  if (existsSync(`${pathWithoutExtension}.mjs`)) {
+    return `${pathWithoutExtension}.mjs`;
+  }
+
+  if (existsSync(`${pathWithoutExtension}.cjs`)) {
+    return `${pathWithoutExtension}.cjs`;
+  }
+};
+
+/**
+ * Creates a stateful dependency graph that is structured in a way that you can get
+ * the dependents of a module from its path.
+ *
+ * Stateful in the sense that it provides a `getter` and an "`updater`". The updater
+ * will receive changes to the files, that can be perceived through some file watching mechanism,
+ * so that it doesn't need to recompute the entire dependency graph but only the parts changed.
+ */
+export const createDependencyGraph = async (directory: string) => {
+  const filePaths = await readAllFilesInsideDirectory(directory);
+  const modulePaths = filePaths.filter(isJavascriptModule);
+  const graph: DependencyGraph = Object.fromEntries(
+    modulePaths.map((path) => [
+      path,
+      {
+        path,
+        dependencyPaths: [],
+        dependentPaths: [],
+        moduleDependencies: [],
+      },
+    ]),
+  );
+
+  const getDependencyPaths = async (filePath: string) => {
+    const contents = await fs.readFile(filePath, 'utf8');
+    const importedPaths = isJavascriptModule(filePath)
+      ? resolvePathAliases(getImportedModules(contents), path.dirname(filePath))
+      : [];
+    const importedPathsRelativeToDirectory = importedPaths.map(
+      (dependencyPath) => {
+        const isModulePath = !dependencyPath.startsWith('.');
+
+        /*
+          path.isAbsolute will return false if the path looks like JavaScript module imports
+          e.g. path.isAbsolute('react-dom/server') will return false, but for our purposes this
+          path is not a relative one.
+        */
+        if (isModulePath || path.isAbsolute(dependencyPath)) {
+          return dependencyPath;
+        }
+
+        let pathToDependencyFromDirectory = path.resolve(
+          /*
+            path.resolve resolves paths differently from what imports on javascript do.
+
+            So if we wouldn't do this, for a template at "/path/to/template.tsx" with a dependency path of "./other-template" 
+            would end up going into /path/to/template.tsx/other-template instead of /path/to/other-template which is the
+            one the import is meant to go to
+          */
+          path.dirname(filePath),
+          dependencyPath,
+        );
+
+        let isDirectory = false;
+        try {
+          // will throw if the the file is not existent
+          isDirectory = statSync(pathToDependencyFromDirectory).isDirectory();
+        } catch {
+          // do nothing
+        }
+        if (isDirectory) {
+          const pathToSubDirectory = pathToDependencyFromDirectory;
+          const pathWithExtension = checkFileExtensionsUntilItExists(
+            `${pathToSubDirectory}/index`,
+          );
+          if (pathWithExtension) {
+            pathToDependencyFromDirectory = pathWithExtension;
+          } else {
+            console.warn(
+              `Could not find index file for directory at ${pathToDependencyFromDirectory}. This is probably going to cause issues with both hot reloading and your code.`,
+            );
+          }
+        }
+
+        const extension = path.extname(pathToDependencyFromDirectory);
+        const pathWithEnsuredExtension = (() => {
+          if (
+            extension.length > 0 &&
+            existsSync(pathToDependencyFromDirectory)
+          ) {
+            return pathToDependencyFromDirectory;
+          }
+          if (javascriptExtensions.includes(extension)) {
+            return checkFileExtensionsUntilItExists(
+              pathToDependencyFromDirectory.replace(extension, ''),
+            );
+          }
+          return checkFileExtensionsUntilItExists(
+            pathToDependencyFromDirectory,
+          );
+        })();
+
+        if (pathWithEnsuredExtension) {
+          pathToDependencyFromDirectory = pathWithEnsuredExtension;
+        } else {
+          console.warn(
+            `Could not find file at ${pathToDependencyFromDirectory}`,
+          );
+        }
+
+        return pathToDependencyFromDirectory;
+      },
+    );
+
+    const moduleDependencies = importedPathsRelativeToDirectory.filter(
+      (dependencyPath) =>
+        !dependencyPath.startsWith('.') && !path.isAbsolute(dependencyPath),
+    );
+
+    const nonNodeModuleImportPathsRelativeToDirectory =
+      importedPathsRelativeToDirectory.filter(
+        (dependencyPath) =>
+          dependencyPath.startsWith('.') || path.isAbsolute(dependencyPath),
+      );
+
+    return {
+      dependencyPaths: nonNodeModuleImportPathsRelativeToDirectory,
+      moduleDependencies,
+    };
+  };
+
+  const updateModuleDependenciesInGraph = async (moduleFilePath: string) => {
+    if (graph[moduleFilePath] === undefined) {
+      graph[moduleFilePath] = {
+        path: moduleFilePath,
+        dependencyPaths: [],
+        dependentPaths: [],
+        moduleDependencies: [],
+      };
+    }
+
+    const { moduleDependencies, dependencyPaths: newDependencyPaths } =
+      await getDependencyPaths(moduleFilePath);
+
+    graph[moduleFilePath].moduleDependencies = moduleDependencies;
+
+    // we go through these to remove the ones that don't exist anymore
+    for (const dependencyPath of graph[moduleFilePath].dependencyPaths) {
+      // Looping through only the ones that were on the dependencyPaths but are not
+      // in the newDependencyPaths
+      if (newDependencyPaths.includes(dependencyPath)) continue;
+
+      const dependencyModule = graph[dependencyPath];
+      if (dependencyModule !== undefined) {
+        dependencyModule.dependentPaths =
+          dependencyModule.dependentPaths.filter(
+            (dependentPath) => dependentPath !== moduleFilePath,
+          );
+      }
+    }
+
+    graph[moduleFilePath].dependencyPaths = newDependencyPaths;
+
+    for (const dependencyPath of newDependencyPaths) {
+      if (graph[dependencyPath] === undefined) {
+        /*
+          This import path might have not been initialized as it can be outside
+          of the original directory we looked into.
+        */
+        await updateModuleDependenciesInGraph(dependencyPath);
+      }
+
+      const dependencyModule = graph[dependencyPath];
+
+      if (dependencyModule === undefined) {
+        throw new Error(
+          `Loading the dependency path ${dependencyPath} did not initialize it at all. This is a bug in React PDF.`,
+        );
+      }
+
+      if (!dependencyModule.dependentPaths.includes(moduleFilePath)) {
+        dependencyModule.dependentPaths.push(moduleFilePath);
+      }
+    }
+  };
+
+  for (const filePath of modulePaths) {
+    await updateModuleDependenciesInGraph(filePath);
+  }
+
+  const removeModuleFromGraph = (filePath: string) => {
+    const module = graph[filePath];
+    if (module) {
+      for (const dependencyPath of module.dependencyPaths) {
+        if (graph[dependencyPath]) {
+          graph[dependencyPath].dependentPaths = graph[
+            dependencyPath
+          ]!.dependentPaths.filter(
+            (dependentPath) => dependentPath !== filePath,
+          );
+        }
+      }
+      delete graph[filePath];
+    }
+  };
+
+  return [
+    graph,
+    async (event: EventName, pathToModified: string) => {
+      switch (event) {
+        case 'change':
+          if (isJavascriptModule(pathToModified)) {
+            await updateModuleDependenciesInGraph(pathToModified);
+          }
+          break;
+        case 'add':
+          if (isJavascriptModule(pathToModified)) {
+            await updateModuleDependenciesInGraph(pathToModified);
+          }
+          break;
+        case 'addDir': {
+          const filesInsideAddedDirectory =
+            await readAllFilesInsideDirectory(pathToModified);
+          const modulesInsideAddedDirectory =
+            filesInsideAddedDirectory.filter(isJavascriptModule);
+          for (const filePath of modulesInsideAddedDirectory) {
+            await updateModuleDependenciesInGraph(filePath);
+          }
+          break;
+        }
+        case 'unlink':
+          if (isJavascriptModule(pathToModified)) {
+            removeModuleFromGraph(pathToModified);
+          }
+          break;
+        case 'unlinkDir': {
+          const filesInsideDeletedDirectory =
+            await readAllFilesInsideDirectory(pathToModified);
+          const modulesInsideDeletedDirectory =
+            filesInsideDeletedDirectory.filter(isJavascriptModule);
+          for (const filePath of modulesInsideDeletedDirectory) {
+            removeModuleFromGraph(filePath);
+          }
+          break;
+        }
+      }
+    },
+    {
+      /**
+       * Resolves all modules that depend on the specified module, directly or indirectly.
+       *
+       * @param pathToModule - The path to the module whose dependents we want to find
+       * @returns An array of paths to all modules that depend on the specified module
+       */
+      resolveDependentsOf: function resolveDependentsOf(
+        pathToModule: string,
+      ): string[] {
+        const dependentPaths = new Set<string>();
+        const stack: string[] = [pathToModule];
+
+        while (stack.length > 0) {
+          const currentPath = stack.pop()!;
+          const moduleEntry = graph[currentPath];
+
+          if (!moduleEntry) continue;
+
+          for (const dependentPath of moduleEntry.dependentPaths) {
+            if (
+              dependentPaths.has(dependentPath) ||
+              dependentPath === pathToModule
+            )
+              continue;
+
+            dependentPaths.add(dependentPath);
+            stack.push(dependentPath);
+          }
+        }
+
+        return [...dependentPaths.values()];
+      },
+    },
+  ] as const;
+};