Add src/package docs

packages/env-loader/src/index.ts

@@ -8,15 +8,60 @@ export type EnvVars = {
   [key: string]: string | boolean
 }
 
-export const processEnv = async (command: string): Promise<void> => {
+/**
+ * Processes and sets up the environment variables, CMS feature flags, and CLI
+ * options before executing a given shell command. This function integrates data
+ * from multiple sources (CLI, environment files, and CMS) into `process.env`
+ * and then spawns the specified command.
+ *
+ * Behavior:
+ * 1. **CLI Options and Arguments**: - Parses command-line arguments and options
+ *    using `getCliOptionsAndArgs`.
+ *
+ * 2. **Environment Variables**: - Loads environment variables from a file
+ *    specific to `process.env.APP_ENV`.
+ *
+ * 3. **CMS Feature Flags**: - Fetches feature flags from a Drupal CMS instance
+ *    if `APP_ENV` is not `test`. - For `test` environments, skips CMS flag
+ *    fetching to avoid CI failures. - Combines CLI options, environment file
+ *    variables, and CMS flags into `process.env`.
+ *
+ * 4. **Command Execution**: - Spawns the given shell command with any
+ *    additional arguments passed from the CLI. - Uses `stdio: 'inherit'` to
+ *    mirror command output in real-time. - Exits the parent process with the
+ *    same exit code as the spawned command.
+ *
+ * Dependencies:
+ * - `getCliOptionsAndArgs` for parsing CLI options and arguments.
+ * - `getEnvFileVars` for loading environment-specific variables.
+ * - `getCmsFeatureFlags` for fetching CMS feature flags.
+ * - `child_process.spawn` for executing the shell command.
+ *
+ * Example Usage:
+ * ```ts
+ * await processEnv('next build');
+ * ```
+ *
+ * Notes:
+ * - CMS feature flags are only fetched if the environment is not `test` to
+ *   avoid breaking CI pipelines.
+ * - The function combines multiple sources of environment variables to ensure a
+ *   fully configured environment.
+ */
+export const processEnv = async (
+  /**
+   * The shell command to be executed, with additional arguments passed through.
+   */
+  command: string
+): Promise<void> => {
   // CLI
   const { args: cliArgs, options: cliOptions } = getCliOptionsAndArgs()
 
   // ENV FILE
   const envVars = getEnvFileVars(process.env.APP_ENV)
 
   // CMS FEATURE FLAGS
-  let cmsFeatureFlags
+  let cmsFeatureFlags // EnvVars, but TypeScript gets angry when assigning a boolean to a property of process.env
   if (process.env.APP_ENV === 'test') {
     // For now, don't fetch CMS feature flags for tests. Will fail CI.
     cmsFeatureFlags = {}

packages/proxy-fetcher/src/index.ts

@@ -1,9 +1,54 @@
 import crossFetch from 'cross-fetch'
 import { SocksProxyAgent } from 'socks-proxy-agent'
 
-export const getFetcher =
-  (baseUrl: string, debug: boolean = false) =>
-  async (input: RequestInfo, init: RequestInit = {}) => {
+/**
+ * Creates a custom fetcher function with support for SOCKS proxying,
+ * certificate management, and automatic retrying of failed requests. The
+ * fetcher adapts based on the environment and target host, ensuring
+ * compatibility with internal VA servers and local development setups.
+ *
+ * Behavior:
+ * - Adds custom certificate authority (CA) files when the target host matches
+ *   specific VA domains.
+ * - Configures a SOCKS proxy for local environments or when certain conditions
+ *   are met.
+ * - Retries failed requests up to 5 times using the `p-retry` library for
+ *   improved resilience.
+ * - Logs request failures based on the `debug` flag and the retry attempt.
+ *
+ * Example Usage:
+ * ```ts
+ * const fetcher = getFetcher('https://va-gov-cms.ddev.site', true);
+ * const response = await fetcher('https://example.com/flags_list', { method: 'GET' });
+ * const data = await response.json();
+ * ```
+ */
+export const getFetcher = (
+  /**
+   * The base URL for the Drupal instance. (e.g. https://va-gov-cms.ddev.site)
+   */
+  baseUrl: string,
+  /**
+   * Whether to enable debug mode, which logs detailed request failure
+   * information.
+   */
+  debug: boolean = false
+) =>
+  /**
+   * Fetches the resource at `input`, using the SOCKS proxy and managing
+   * certificates and retries as needed.
+   */
+  async function fetcher(
+    /**
+     * The resource to fetch. Must include the base URL for the Drupal instance.
+     * (e.g. htts://va-gov-cms.ddev.site/flags_list)
+     */
+    input: RequestInfo,
+    /**
+     * Any parameters to pass to the underlying `crossFetch` call.
+     */
+    init: RequestInit = {}
+  ) {
     const url = new URL(baseUrl)
     const host = url.host