shakapacker 8.4.0 → 9.7.0

data/package/configExporter/fileWriter.ts

@@ -0,0 +1,112 @@
+import { writeFileSync, mkdirSync, existsSync } from "fs"
+import { resolve, dirname, relative, isAbsolute, basename } from "path"
+import { tmpdir } from "os"
+import { FileOutput } from "./types"
+
+/**
+ * Handles writing config exports to files.
+ * Supports single file output or multiple files (one per config).
+ */
+export class FileWriter {
+  /**
+   * Write multiple config files (one per config in array)
+   */
+  static writeMultipleFiles(outputs: FileOutput[], targetDir: string): void {
+    // Ensure directory exists
+    FileWriter.ensureDirectory(targetDir)
+
+    // Write each file
+    outputs.forEach((output) => {
+      const safeName = basename(output.filename)
+      const filePath = resolve(targetDir, safeName)
+      FileWriter.validateOutputPath(filePath)
+      FileWriter.writeFile(filePath, output.content)
+      console.log(`[Config Exporter] Created: ${filePath}`)
+    })
+
+    console.log(
+      `[Config Exporter] Exported ${outputs.length} config file(s) to ${targetDir}`
+    )
+  }
+
+  /**
+   * Write a single file
+   */
+  static writeSingleFile(filePath: string, content: string): void {
+    // Ensure parent directory exists
+    const dir = dirname(filePath)
+    FileWriter.ensureDirectory(dir)
+
+    FileWriter.validateOutputPath(filePath)
+    FileWriter.writeFile(filePath, content)
+    console.log(`[Config Exporter] Created: ${filePath}`)
+  }
+
+  /**
+   * Generate filename for a config export
+   * Format without build: {bundler}-{env}-{type}.{ext}
+   * Format with build: {bundler}-{build}-{type}.{ext}
+   *
+   * @param bundler - The bundler type (webpack, rspack)
+   * @param env - The environment (development, production, test)
+   * @param configType - Type of config. Built-in: "client", "server", "all", "client-hmr". Custom: any string from outputs array
+   * @param format - Output format (yaml, json, inspect)
+   * @param buildName - Optional build name that overrides env in filename
+   *
+   * @example
+   * // Built-in types
+   * generateFilename("webpack", "development", "client", "yaml")
+   * // => "webpack-development-client.yml"
+   *
+   * @example
+   * // Custom output names
+   * generateFilename("webpack", "development", "client-modern", "yaml", "dev-hmr")
+   * // => "webpack-dev-hmr-client-modern.yml"
+   */
+  static generateFilename(
+    bundler: string,
+    env: string,
+    configType: string,
+    format: "yaml" | "json" | "inspect",
+    buildName?: string
+  ): string {
+    let ext: string
+    if (format === "yaml") {
+      ext = "yml"
+    } else if (format === "json") {
+      ext = "json"
+    } else {
+      ext = "txt"
+    }
+    const name = buildName || env
+    return `${bundler}-${name}-${configType}.${ext}`
+  }
+
+  private static writeFile(filePath: string, content: string): void {
+    writeFileSync(filePath, content, "utf8")
+  }
+
+  private static ensureDirectory(dir: string): void {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+  }
+
+  /**
+   * Validate output path and warn if writing outside cwd
+   */
+  private static validateOutputPath(outputPath: string): void {
+    const absPath = resolve(outputPath)
+    const cwd = process.cwd()
+
+    const isWithin = (base: string, target: string) => {
+      const rel = relative(base, target)
+      return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))
+    }
+    if (!isWithin(cwd, absPath) && !isWithin(tmpdir(), absPath)) {
+      console.warn(
+        `[Config Exporter] Warning: Writing to ${absPath} which is outside current directory (${cwd}) or temp (${tmpdir()})`
+      )
+    }
+  }
+}

data/package/configExporter/index.ts

@@ -0,0 +1,15 @@
+export { run } from "./cli"
+export type {
+  ExportOptions,
+  ConfigMetadata,
+  FileOutput,
+  BundlerConfigFile,
+  BuildConfig,
+  ResolvedBuildConfig,
+  BuildValidationResult
+} from "./types"
+export { YamlSerializer } from "./yamlSerializer"
+export { FileWriter } from "./fileWriter"
+export { getDocForKey } from "./configDocs"
+export { ConfigFileLoader, generateSampleConfigFile } from "./configFile"
+export { BuildValidator } from "./buildValidator"

data/package/configExporter/types.ts

@@ -0,0 +1,159 @@
+/**
+ * Environment variable names that can be set by build configurations.
+ * These are the only environment variables that build configs are allowed to set.
+ * This whitelist prevents malicious configs from modifying critical system variables.
+ */
+export const BUILD_ENV_VARS = [
+  "NODE_ENV",
+  "RAILS_ENV",
+  "NODE_OPTIONS",
+  "BABEL_ENV",
+  "WEBPACK_SERVE",
+  "CLIENT_BUNDLE_ONLY",
+  "SERVER_BUNDLE_ONLY"
+] as const
+
+/**
+ * Environment variables that must never be set by build configurations.
+ * Setting these could compromise system security or cause unexpected behavior.
+ */
+export const DANGEROUS_ENV_VARS = [
+  "PATH",
+  "HOME",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "DYLD_LIBRARY_PATH",
+  "DYLD_INSERT_LIBRARIES"
+] as const
+
+/**
+ * Type predicate to check if a string is in the BUILD_ENV_VARS whitelist
+ *
+ * Note: The type assertion is necessary because TypeScript's type system cannot
+ * infer that .includes() on a readonly const array will properly narrow the type.
+ * The assertion is safe because we're only widening the type for the includes() check.
+ */
+export function isBuildEnvVar(
+  key: string
+): key is (typeof BUILD_ENV_VARS)[number] {
+  return (BUILD_ENV_VARS as readonly string[]).includes(key)
+}
+
+/**
+ * Type predicate to check if a string is in the DANGEROUS_ENV_VARS blacklist
+ *
+ * Note: The type assertion is necessary because TypeScript's type system cannot
+ * infer that .includes() on a readonly const array will properly narrow the type.
+ * The assertion is safe because we're only widening the type for the includes() check.
+ */
+export function isDangerousEnvVar(
+  key: string
+): key is (typeof DANGEROUS_ENV_VARS)[number] {
+  return (DANGEROUS_ENV_VARS as readonly string[]).includes(key)
+}
+
+/**
+ * Default directory for config exports when using --doctor or file output modes.
+ */
+export const DEFAULT_EXPORT_DIR = "shakapacker-config-exports"
+
+/**
+ * Default config file path for bundler build configurations.
+ */
+export const DEFAULT_CONFIG_FILE = "config/shakapacker-builds.yml"
+
+export interface ExportOptions {
+  doctor?: boolean
+  saveDir?: string
+  stdout?: boolean
+  bundler?: "webpack" | "rspack"
+  env?: "development" | "production" | "test"
+  clientOnly?: boolean
+  serverOnly?: boolean
+  output?: string
+  format?: "yaml" | "json" | "inspect"
+  annotate?: boolean
+  verbose?: boolean
+  depth?: number | null
+  help?: boolean
+  // New config file options
+  init?: boolean
+  ssr?: boolean
+  configFile?: string
+  build?: string
+  listBuilds?: boolean
+  allBuilds?: boolean
+  // Validation options
+  validate?: boolean
+  validateBuild?: string
+}
+
+export interface ConfigMetadata {
+  exportedAt: string
+  bundler: string
+  environment: string
+  configFile: string
+  /**
+   * Type of webpack/rspack config output.
+   * Built-in types: "client", "server", "all", "client-hmr"
+   * Custom types: Any string matching your outputs array (e.g., "client-modern", "client-legacy", "server-bundle")
+   */
+  configType: string
+  configCount: number
+  buildName?: string // New: name of the build from config file
+  environmentVariables: {
+    NODE_ENV?: string
+    RAILS_ENV?: string
+    CLIENT_BUNDLE_ONLY?: string
+    SERVER_BUNDLE_ONLY?: string
+    WEBPACK_SERVE?: string
+    HMR?: string
+  }
+}
+
+export interface FileOutput {
+  filename: string
+  content: string
+  metadata: ConfigMetadata
+}
+
+// Config file schema types
+export interface BundlerConfigFile {
+  default_bundler?: "webpack" | "rspack"
+  shakapacker_doctor_default_builds_here?: boolean
+  builds: Record<string, BuildConfig>
+}
+
+export interface BuildConfig {
+  description?: string
+  bundler?: "webpack" | "rspack"
+  dev_server?: boolean
+  environment?: Record<string, string>
+  bundler_env?: Record<string, string | boolean>
+  outputs?: string[]
+  config?: string
+}
+
+export interface ResolvedBuildConfig {
+  name: string
+  description?: string
+  bundler: "webpack" | "rspack"
+  environment: Record<string, string>
+  bundlerEnvArgs: string[] // Converted bundler_env to CLI args
+  outputs: string[]
+  configFile?: string
+}
+
+export interface BuildValidationResult {
+  buildName: string
+  success: boolean
+  errors: string[]
+  warnings: string[]
+  output: string[]
+  outputs?: string[] // Build outputs (e.g., ["client", "server"])
+  configFile?: string // Config file path if specified
+  outputPath?: string // Output directory where files are written
+  startTime?: number // Unix timestamp in milliseconds
+  endTime?: number // Unix timestamp in milliseconds
+  duration?: number // Duration in milliseconds
+}

data/package/configExporter/yamlSerializer.ts

@@ -0,0 +1,391 @@
+import { relative, isAbsolute } from "path"
+import { ConfigMetadata } from "./types"
+import { getDocForKey } from "./configDocs"
+
+/**
+ * Serializes webpack/rspack config to YAML format with optional inline documentation.
+ * Handles functions, RegExp, and special objects that don't serialize well to standard YAML.
+ */
+export class YamlSerializer {
+  private annotate: boolean
+
+  private appRoot: string
+
+  constructor(options: { annotate: boolean; appRoot: string }) {
+    this.annotate = options.annotate
+    this.appRoot = options.appRoot
+  }
+
+  /**
+   * Serialize a config object to YAML string with metadata header
+   */
+  serialize(config: unknown, metadata: ConfigMetadata): string {
+    const output: string[] = []
+
+    // Add metadata header
+    output.push(YamlSerializer.createHeader(metadata))
+    output.push("")
+
+    // Serialize the config
+    output.push(this.serializeValue(config, 0, ""))
+
+    return output.join("\n")
+  }
+
+  private static createHeader(metadata: ConfigMetadata): string {
+    const lines: string[] = []
+    lines.push(`# ${"=".repeat(77)}`)
+    lines.push("# Webpack/Rspack Configuration Export")
+    lines.push(`# Generated: ${metadata.exportedAt}`)
+    lines.push(`# Environment: ${metadata.environment}`)
+    lines.push(`# Bundler: ${metadata.bundler}`)
+    lines.push(`# Config Type: ${metadata.configType}`)
+    if (metadata.configCount > 1) {
+      lines.push(`# Total Configs: ${metadata.configCount}`)
+    }
+    lines.push(`# ${"=".repeat(77)}`)
+    return lines.join("\n")
+  }
+
+  private serializeValue(
+    value: unknown,
+    indent: number,
+    keyPath: string
+  ): string {
+    if (value === null || value === undefined) {
+      return "null"
+    }
+
+    if (typeof value === "boolean") {
+      return value.toString()
+    }
+
+    if (typeof value === "number") {
+      return value.toString()
+    }
+
+    if (typeof value === "string") {
+      return this.serializeString(value, indent)
+    }
+
+    if (typeof value === "function") {
+      return this.serializeFunction(
+        value as (...args: unknown[]) => unknown,
+        indent
+      )
+    }
+
+    if (value instanceof RegExp) {
+      // Extract pattern without surrounding slashes: "/pattern/flags" -> "pattern"
+      // Include flags as inline comment when present for semantic clarity
+      const regexStr = value.toString()
+      const lastSlash = regexStr.lastIndexOf("/")
+      const pattern = regexStr.slice(1, lastSlash)
+      const flags = regexStr.slice(lastSlash + 1)
+
+      const serializedPattern = this.serializeString(pattern, indent)
+
+      // Add flags as inline comment if present (e.g., "pattern" # flags: gi)
+      if (flags) {
+        return `${serializedPattern} # flags: ${flags}`
+      }
+
+      return serializedPattern
+    }
+
+    if (Array.isArray(value)) {
+      return this.serializeArray(value, indent, keyPath)
+    }
+
+    if (typeof value === "object") {
+      return this.serializeObject(
+        value as Record<string, unknown>,
+        indent,
+        keyPath
+      )
+    }
+
+    // Handle remaining types explicitly
+    if (typeof value === "symbol") return value.toString()
+    if (typeof value === "bigint") return value.toString()
+
+    // All remaining types are primitives (string, number, boolean, null, undefined)
+    // that String() handles safely - cast to exclude objects since we've already handled them
+    return String(value as string | number | boolean | null | undefined)
+  }
+
+  private serializeString(str: string, indent: number = 0): string {
+    // Make absolute paths relative for cleaner output
+    const cleaned = this.makePathRelative(str)
+
+    // Handle multiline strings
+    if (cleaned.includes("\n")) {
+      const lines = cleaned.split("\n")
+      const lineIndent = " ".repeat(indent + 2)
+      return `|\n${lines.map((line) => lineIndent + line).join("\n")}`
+    }
+
+    // Escape strings that need quoting in YAML
+    // YAML has many special characters that can cause parsing errors:
+    // : # ' " (basic delimiters)
+    // [ ] { } (flow collections)
+    // * & ! @ ` (special constructs: aliases, anchors, tags)
+    if (
+      cleaned.includes(":") ||
+      cleaned.includes("#") ||
+      cleaned.includes("'") ||
+      cleaned.includes('"') ||
+      cleaned.includes("[") ||
+      cleaned.includes("]") ||
+      cleaned.includes("{") ||
+      cleaned.includes("}") ||
+      cleaned.includes("*") ||
+      cleaned.includes("&") ||
+      cleaned.includes("!") ||
+      cleaned.includes("@") ||
+      cleaned.includes("`") ||
+      cleaned.startsWith(" ") ||
+      cleaned.endsWith(" ")
+    ) {
+      // Escape backslashes first, then quotes to avoid double-escaping
+      return `"${cleaned.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+    }
+
+    return cleaned
+  }
+
+  private serializeFunction(
+    fn: (...args: unknown[]) => unknown,
+    indent: number = 0
+  ): string {
+    // Get function source code
+    const source = fn.toString()
+
+    // Pretty-print function: maintain readable formatting
+    const lines = source.split("\n")
+
+    // For very long functions, truncate
+    const maxLines = 50
+    const truncated = lines.length > maxLines
+    const displayLines = truncated ? lines.slice(0, maxLines) : lines
+
+    // Clean up indentation while preserving structure
+    const indentLevels = displayLines
+      .filter((l) => l.trim().length > 0)
+      .map((l) => l.match(/^\s*/)?.[0].length || 0)
+    const minIndent = indentLevels.length > 0 ? Math.min(...indentLevels) : 0
+
+    const formatted =
+      displayLines.map((line) => line.substring(minIndent)).join("\n") +
+      (truncated ? "\n..." : "")
+
+    // Use serializeString to properly handle multiline with correct indentation
+    return this.serializeString(formatted, indent)
+  }
+
+  private serializeArray(
+    arr: unknown[],
+    indent: number,
+    keyPath: string
+  ): string {
+    if (arr.length === 0) {
+      return "[]"
+    }
+
+    const lines: string[] = []
+    const itemIndent = " ".repeat(indent + 2)
+    const contentIndent = " ".repeat(indent + 4)
+
+    arr.forEach((item, index) => {
+      const itemPath = `${keyPath}[${index}]`
+
+      // Check if this is a plugin object and add its name as a comment
+      const pluginName = YamlSerializer.getConstructorName(item)
+      const isPlugin = pluginName && /(^|\.)plugins\[\d+\]/.test(itemPath)
+      const isEmpty =
+        typeof item === "object" &&
+        item !== null &&
+        !Array.isArray(item) &&
+        Object.keys(item).length === 0
+
+      // For non-empty plugins, add comment before the plugin
+      // For empty plugins, the name will be shown inline
+      if (isPlugin && !isEmpty) {
+        lines.push(`${itemIndent}# ${pluginName}`)
+      }
+
+      const serialized = this.serializeValue(item, indent + 4, itemPath)
+
+      // Add documentation for array items if available
+      if (this.annotate) {
+        const doc = getDocForKey(itemPath)
+        if (doc) {
+          lines.push(`${itemIndent}# ${doc}`)
+        }
+      }
+
+      if (typeof item === "object" && !Array.isArray(item) && item !== null) {
+        // For objects in arrays, emit marker on its own line and indent content
+        lines.push(`${itemIndent}-`)
+        const nonEmptyLines = serialized
+          .split("\n")
+          .filter((line: string) => line.trim().length > 0)
+        // Compute minimum leading whitespace to preserve relative indentation
+        const indentLevels = nonEmptyLines.map(
+          (line: string) => line.match(/^\s*/)?.[0].length || 0
+        )
+        const minIndent =
+          indentLevels.length > 0 ? Math.min(...indentLevels) : 0
+        nonEmptyLines.forEach((line: string) => {
+          // Remove only the common indent, preserving relative indentation
+          lines.push(contentIndent + line.substring(minIndent))
+        })
+      } else if (serialized.includes("\n")) {
+        // For multiline values, emit marker on its own line and indent content
+        lines.push(`${itemIndent}-`)
+        const nonEmptyLines = serialized
+          .split("\n")
+          .filter((line: string) => line.trim().length > 0)
+        // Compute minimum leading whitespace to preserve relative indentation
+        const indentLevels = nonEmptyLines.map(
+          (line: string) => line.match(/^\s*/)?.[0].length || 0
+        )
+        const minIndent =
+          indentLevels.length > 0 ? Math.min(...indentLevels) : 0
+        nonEmptyLines.forEach((line: string) => {
+          // Remove only the common indent, preserving relative indentation
+          lines.push(contentIndent + line.substring(minIndent))
+        })
+      } else {
+        // For simple values, keep on same line
+        lines.push(`${itemIndent}- ${serialized}`)
+      }
+    })
+
+    return `\n${lines.join("\n")}`
+  }
+
+  private serializeObject(
+    obj: Record<string, unknown>,
+    indent: number,
+    keyPath: string
+  ): string {
+    const keys = Object.keys(obj).sort()
+    const constructorName = YamlSerializer.getConstructorName(obj)
+
+    // For empty objects, show constructor name if available
+    if (keys.length === 0) {
+      if (constructorName) {
+        return `{} # ${constructorName}`
+      }
+      return "{}"
+    }
+
+    const lines: string[] = []
+    const keyIndent = " ".repeat(indent)
+    const valueIndent = " ".repeat(indent + 2)
+
+    keys.forEach((key) => {
+      const value = obj[key]
+      const fullKeyPath = keyPath ? `${keyPath}.${key}` : key
+
+      // Add documentation comment if available and annotation is enabled
+      if (this.annotate) {
+        const doc = getDocForKey(fullKeyPath)
+        if (doc) {
+          lines.push(`${keyIndent}# ${doc}`)
+        }
+      }
+
+      // Handle multiline strings specially with block scalar
+      if (typeof value === "string" && value.includes("\n")) {
+        lines.push(`${keyIndent}${key}: |`)
+        for (const line of value.split("\n")) {
+          lines.push(`${valueIndent}${line}`)
+        }
+      } else if (value instanceof RegExp || typeof value === "function") {
+        // Handle RegExp and functions explicitly before the generic object check
+        // to prevent them from being treated as empty objects (RegExp/functions
+        // have no enumerable keys but should serialize as their string representation)
+        const serialized = this.serializeValue(value, indent + 2, fullKeyPath)
+        lines.push(`${keyIndent}${key}: ${serialized}`)
+      } else if (
+        typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value)
+      ) {
+        if (Object.keys(value).length === 0) {
+          lines.push(`${keyIndent}${key}: {}`)
+        } else {
+          lines.push(`${keyIndent}${key}:`)
+          const nestedLines = this.serializeObject(
+            value as Record<string, unknown>,
+            indent + 2,
+            fullKeyPath
+          )
+          lines.push(nestedLines)
+        }
+      } else if (Array.isArray(value)) {
+        if (value.length === 0) {
+          lines.push(`${keyIndent}${key}: []`)
+        } else {
+          lines.push(`${keyIndent}${key}:`)
+          const arrayLines = this.serializeArray(value, indent + 2, fullKeyPath)
+          lines.push(arrayLines)
+        }
+      } else {
+        const serialized = this.serializeValue(value, indent + 2, fullKeyPath)
+        lines.push(`${keyIndent}${key}: ${serialized}`)
+      }
+    })
+
+    return lines.join("\n")
+  }
+
+  private makePathRelative(str: string): string {
+    if (!isAbsolute(str)) return str
+
+    // Convert absolute paths to relative paths using path.relative
+    const rel = relative(this.appRoot, str)
+
+    if (rel === "") {
+      return "."
+    }
+
+    // If path is outside appRoot or already absolute, keep original
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      return str
+    }
+
+    return `./${rel}`
+  }
+
+  /**
+   * Extracts the constructor name from an object
+   * Returns null for plain objects (Object constructor) or objects without prototypes
+   */
+  private static getConstructorName(obj: unknown): string | null {
+    if (!obj || typeof obj !== "object") return null
+    if (Array.isArray(obj)) return null
+
+    // Use Object.getPrototypeOf for safer access to constructor
+    // This handles Object.create(null) and unusual prototypes correctly
+    try {
+      const proto = Object.getPrototypeOf(obj) as {
+        constructor?: { name?: string }
+      } | null
+      if (!proto || proto === Object.prototype) return null
+
+      const { constructor } = proto
+      if (!constructor || typeof constructor !== "function") return null
+
+      const constructorName = constructor.name
+      if (!constructorName || constructorName === "Object") return null
+
+      return constructorName
+    } catch {
+      // Handle frozen objects or other edge cases
+      return null
+    }
+  }
+}

data/package/dev_server.ts

@@ -0,0 +1,27 @@
+// These are the raw shakapacker dev server config settings from the YML file with ENV overrides applied.
+import type { DevServerConfig, Config } from "./types"
+
+const { isBoolean } = require("./utils/helpers")
+const config = require("./config") as Config
+
+const envFetch = (key: string): string | boolean | undefined => {
+  const value = process.env[key]
+  if (!value) return undefined
+  return isBoolean(value) ? JSON.parse(value) : value
+}
+
+const devServerConfig: DevServerConfig | undefined = config.dev_server
+
+if (devServerConfig) {
+  const envPrefix = devServerConfig.env_prefix || "SHAKAPACKER_DEV_SERVER"
+
+  Object.keys(devServerConfig).forEach((key) => {
+    const envValue = envFetch(`${envPrefix}_${key.toUpperCase()}`)
+    if (envValue !== undefined) {
+      // Use bracket notation to avoid ASI issues
+      ;(devServerConfig as Record<string, unknown>)[key] = envValue
+    }
+  })
+}
+
+export = devServerConfig || {}