shakapacker 9.1.0 → 9.3.0.beta.0

data/package/configExporter/fileWriter.ts

@@ -0,0 +1,96 @@
+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)
+   */
+  writeMultipleFiles(outputs: FileOutput[], targetDir: string): void {
+    // Ensure directory exists
+    this.ensureDirectory(targetDir)
+
+    // Write each file
+    outputs.forEach((output) => {
+      const safeName = basename(output.filename)
+      const filePath = resolve(targetDir, safeName)
+      this.validateOutputPath(filePath)
+      this.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
+   */
+  writeSingleFile(filePath: string, content: string): void {
+    // Ensure parent directory exists
+    const dir = dirname(filePath)
+    this.ensureDirectory(dir)
+
+    this.validateOutputPath(filePath)
+    this.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}
+   * Examples:
+   *   webpack-development-client.yaml
+   *   rspack-production-server.yaml
+   *   webpack-test-all.json
+   *   webpack-development-client-hmr.yaml
+   *   webpack-dev-client.yaml (with build name)
+   *   rspack-cypress-dev-server.yaml (with build name)
+   */
+  generateFilename(
+    bundler: string,
+    env: string,
+    configType: "client" | "server" | "all" | "client-hmr",
+    format: "yaml" | "json" | "inspect",
+    buildName?: string
+  ): string {
+    const ext = format === "yaml" ? "yaml" : format === "json" ? "json" : "txt"
+    const name = buildName || env
+    return `${bundler}-${name}-${configType}.${ext}`
+  }
+
+  private writeFile(filePath: string, content: string): void {
+    writeFileSync(filePath, content, "utf8")
+  }
+
+  private ensureDirectory(dir: string): void {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+  }
+
+  /**
+   * Validate output path and warn if writing outside cwd
+   */
+  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,13 @@
+export { run } from "./cli"
+export type {
+  ExportOptions,
+  ConfigMetadata,
+  FileOutput,
+  BundlerConfigFile,
+  BuildConfig,
+  ResolvedBuildConfig
+} from "./types"
+export { YamlSerializer } from "./yamlSerializer"
+export { FileWriter } from "./fileWriter"
+export { getDocForKey } from "./configDocs"
+export { ConfigFileLoader, generateSampleConfigFile } from "./configFile"

data/package/configExporter/types.ts

@@ -0,0 +1,70 @@
+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
+  configFile?: string
+  build?: string
+  listBuilds?: boolean
+  allBuilds?: boolean
+}
+
+export interface ConfigMetadata {
+  exportedAt: string
+  bundler: string
+  environment: string
+  configFile: string
+  configType: "client" | "server" | "all" | "client-hmr"
+  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
+  }
+}
+
+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"
+  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
+}

data/package/configExporter/yamlSerializer.ts

@@ -0,0 +1,280 @@
+import { ConfigMetadata } from "./types"
+import { getDocForKey } from "./configDocs"
+import { relative, isAbsolute } from "path"
+
+/**
+ * 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: any, metadata: ConfigMetadata): string {
+    const output: string[] = []
+
+    // Add metadata header
+    output.push(this.createHeader(metadata))
+    output.push("")
+
+    // Serialize the config
+    output.push(this.serializeValue(config, 0, ""))
+
+    return output.join("\n")
+  }
+
+  private 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: any, 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)
+    }
+
+    if (value instanceof RegExp) {
+      return this.serializeString(value.toString())
+    }
+
+    if (Array.isArray(value)) {
+      return this.serializeArray(value, indent, keyPath)
+    }
+
+    if (typeof value === "object") {
+      return this.serializeObject(value, indent, keyPath)
+    }
+
+    return String(value)
+  }
+
+  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
+    if (
+      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: Function): 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 minIndent = Math.min(
+      ...displayLines
+        .filter((l) => l.trim().length > 0)
+        .map((l) => l.match(/^\s*/)?.[0].length || 0)
+    )
+
+    const formatted =
+      displayLines.map((line) => line.substring(minIndent)).join("\n") +
+      (truncated ? "\n..." : "")
+
+    // Use serializeString to properly handle multiline
+    return this.serializeString(formatted)
+  }
+
+  private serializeArray(arr: any[], 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}]`
+      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 minIndent = Math.min(
+          ...nonEmptyLines.map(
+            (line: string) => line.match(/^\s*/)?.[0].length || 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 minIndent = Math.min(
+          ...nonEmptyLines.map(
+            (line: string) => line.match(/^\s*/)?.[0].length || 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: any, indent: number, keyPath: string): string {
+    const keys = Object.keys(obj)
+    if (keys.length === 0) {
+      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 (
+        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,
+            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 (typeof str !== "string") return str
+    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
+  }
+}

data/package/dev_server.ts

@@ -18,7 +18,7 @@ if (devServerConfig) {
     const envValue = envFetch(`${envPrefix}_${key.toUpperCase()}`)
     if (envValue !== undefined) {
       // Use bracket notation to avoid ASI issues
-      (devServerConfig as Record<string, unknown>)[key] = envValue
+      ;(devServerConfig as Record<string, unknown>)[key] = envValue
     }
   })
 }

data/package/environments/__type-tests__/rspack-plugin-compatibility.ts

@@ -6,22 +6,28 @@
  * These tests will fail at compile time if the types are not compatible.
  */
 
-import type { RspackPlugin, RspackPluginInstance } from '../types'
+import type { RspackPlugin, RspackPluginInstance } from "../types"
 
 // Test 1: RspackPlugin should be assignable to RspackPluginInstance
-const testPluginToInstance = (plugin: RspackPlugin): RspackPluginInstance => plugin
+const testPluginToInstance = (plugin: RspackPlugin): RspackPluginInstance =>
+  plugin
 
 // Test 2: RspackPluginInstance should be assignable to RspackPlugin
-const testInstanceToPlugin = (instance: RspackPluginInstance): RspackPlugin => instance
+const testInstanceToPlugin = (instance: RspackPluginInstance): RspackPlugin =>
+  instance
 
 // Test 3: Array compatibility
-const testArrayCompatibility = (plugins: RspackPlugin[]): RspackPluginInstance[] => plugins
+const testArrayCompatibility = (
+  plugins: RspackPlugin[]
+): RspackPluginInstance[] => plugins
 const testArrayCompatibilityReverse = (
   instances: RspackPluginInstance[]
 ): RspackPlugin[] => instances
 
 // Test 4: Optional parameter compatibility
-const testOptionalParam = (plugin?: RspackPlugin): RspackPluginInstance | undefined => plugin
+const testOptionalParam = (
+  plugin?: RspackPlugin
+): RspackPluginInstance | undefined => plugin
 const testOptionalParamReverse = (
   instance?: RspackPluginInstance
 ): RspackPlugin | undefined => instance

data/package/environments/base.ts

@@ -53,13 +53,13 @@ const getEntryObject = (): Entry => {
   if (config.source_entry_path === "/" && config.nested_entries) {
     throw new Error(
       `Invalid Shakapacker configuration detected!\n\n` +
-      `You have set source_entry_path to '/' with nested_entries enabled.\n` +
-      `This would create webpack entry points for EVERY file in your source directory,\n` +
-      `which would severely impact build performance.\n\n` +
-      `To fix this issue, either:\n` +
-      `1. Set 'nested_entries: false' in your shakapacker.yml\n` +
-      `2. Change 'source_entry_path' to a specific subdirectory (e.g., 'packs')\n` +
-      `3. Or use both options for better organization of your entry points`
+        `You have set source_entry_path to '/' with nested_entries enabled.\n` +
+        `This would create webpack entry points for EVERY file in your source directory,\n` +
+        `which would severely impact build performance.\n\n` +
+        `To fix this issue, either:\n` +
+        `1. Set 'nested_entries: false' in your shakapacker.yml\n` +
+        `2. Change 'source_entry_path' to a specific subdirectory (e.g., 'packs')\n` +
+        `3. Or use both options for better organization of your entry points`
     )
   }
 
@@ -73,7 +73,7 @@ const getEntryObject = (): Entry => {
     const previousPaths = entries[name]
     if (previousPaths) {
       const pathArray = Array.isArray(previousPaths)
-        ? previousPaths as string[]
+        ? (previousPaths as string[])
         : [previousPaths as string]
       pathArray.push(assetPath)
       entries[name] = pathArray
@@ -89,7 +89,9 @@ const getModulePaths = (): string[] => {
   const result = [resolve(config.source_path)]
 
   if (config.additional_paths) {
-    config.additional_paths.forEach((path: string) => result.push(resolve(path)))
+    config.additional_paths.forEach((path: string) =>
+      result.push(resolve(path))
+    )
   }
   result.push("node_modules")
 
@@ -108,9 +110,13 @@ const baseConfig: Configuration = {
     publicPath: config.publicPath,
 
     // This is required for SRI to work.
-    crossOriginLoading: config.integrity && config.integrity.enabled
-      ? (config.integrity.cross_origin as "anonymous" | "use-credentials" | false)
-      : false
+    crossOriginLoading:
+      config.integrity && config.integrity.enabled
+        ? (config.integrity.cross_origin as
+            | "anonymous"
+            | "use-credentials"
+            | false)
+        : false
   },
   entry: getEntryObject(),
   resolve: {
@@ -135,4 +141,3 @@ const baseConfig: Configuration = {
 }
 
 export = baseConfig
-

data/package/environments/development.ts

@@ -9,7 +9,7 @@ const baseConfig = require("./base")
 const webpackDevServerConfig = require("../webpackDevServerConfig")
 const { runningWebpackDevServer } = require("../env")
 const { moduleExists } = require("../utils/helpers")
-import type { 
+import type {
   WebpackConfigWithDevServer,
   RspackConfigWithDevServer,
   ReactRefreshWebpackPlugin,

data/package/environments/production.ts

@@ -11,7 +11,10 @@ const { merge } = require("webpack-merge")
 const baseConfig = require("./base")
 const { moduleExists } = require("../utils/helpers")
 const config = require("../config")
-import type { Configuration as WebpackConfiguration, WebpackPluginInstance } from "webpack"
+import type {
+  Configuration as WebpackConfiguration,
+  WebpackPluginInstance
+} from "webpack"
 import type { CompressionPluginConstructor } from "./types"
 
 const optimizationPath = resolve(

data/package/index.d.ts

@@ -1,3 +1,50 @@
-declare const _default: any;
-export = _default;
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Manual type definitions for Shakapacker package exports.
+ *
+ * This file is manually maintained because TypeScript cannot infer types
+ * from the `export =` syntax with dynamic require() calls in index.ts.
+ *
+ * When adding/modifying exports in index.ts, update this file accordingly.
+ */
+
+import type { Configuration, RuleSetRule } from "webpack"
+import type { Config, DevServerConfig, Env } from "./types"
+
+/**
+ * The shape of the Shakapacker module exports.
+ * This interface represents the object exported via CommonJS `export =`.
+ */
+interface ShakapackerExports {
+  /** Shakapacker configuration from shakapacker.yml */
+  config: Config
+  /** Development server configuration */
+  devServer: DevServerConfig
+  /** Base webpack/rspack configuration */
+  baseConfig: Configuration
+  /** Environment configuration (railsEnv, nodeEnv, etc.) */
+  env: Env
+  /** Array of webpack/rspack loader rules */
+  rules: RuleSetRule[]
+  /** Check if a module exists in node_modules */
+  moduleExists: (packageName: string) => boolean
+  /** Process a file if a specific loader is available */
+  canProcess: <T = unknown>(
+    rule: string,
+    fn: (modulePath: string) => T
+  ) => T | null
+  /** Whether CSS should be inlined (dev server with HMR) */
+  inliningCss: boolean
+  /** Generate webpack configuration with optional custom config */
+  generateWebpackConfig: (extraConfig?: Configuration) => Configuration
+  /** webpack-merge's merge function */
+  merge: typeof import("webpack-merge").merge
+  /** webpack-merge's mergeWithCustomize function */
+  mergeWithCustomize: typeof import("webpack-merge").mergeWithCustomize
+  /** webpack-merge's mergeWithRules function */
+  mergeWithRules: typeof import("webpack-merge").mergeWithRules
+  /** webpack-merge's unique function */
+  unique: typeof import("webpack-merge").unique
+}
+
+declare const shakapacker: ShakapackerExports
+export = shakapacker