shakapacker 9.3.0.beta.6 → 9.3.0

data/lib/shakapacker.rb

@@ -3,22 +3,86 @@ require "active_support/core_ext/string/inquiry"
 require "active_support/logger"
 require "active_support/tagged_logging"
 
+# = Shakapacker
+#
+# Shakapacker is a Ruby gem that integrates webpack and rspack with Rails applications,
+# providing a modern asset pipeline for JavaScript, CSS, and other web assets.
+#
+# The main Shakapacker module provides singleton-style access to configuration,
+# compilation, and asset manifest functionality. Most methods delegate to a shared
+# {Shakapacker::Instance} object.
+#
+# == Basic Usage
+#
+#   # Access configuration
+#   Shakapacker.config.source_path
+#   #=> Pathname("/path/to/app/packs")
+#
+#   # Check if dev server is running
+#   Shakapacker.dev_server.running?
+#   #=> true
+#
+#   # Look up compiled assets
+#   Shakapacker.manifest.lookup("application.js")
+#   #=> "/packs/application-abc123.js"
+#
+#   # Compile assets
+#   Shakapacker.compile
+#
+# == Configuration
+#
+# Configuration is loaded from +config/shakapacker.yml+ and can be accessed via
+# {Shakapacker.config}. The configuration determines the source paths, output paths,
+# compilation settings, and dev server options.
+#
+# @see Shakapacker::Configuration
+# @see Shakapacker::Instance
 module Shakapacker
   extend self
 
+  # Default environment when RAILS_ENV is not set
   DEFAULT_ENV = "development".freeze
   # Environments that use their RAILS_ENV value for NODE_ENV
   # All other environments (production, staging, etc.) use "production" for webpack optimizations
   DEV_TEST_ENVS = %w[development test].freeze
 
+  # Sets the shared Shakapacker instance
+  #
+  # This is primarily used for testing or advanced customization scenarios.
+  # In most applications, the default instance is sufficient.
+  #
+  # @param instance [Shakapacker::Instance] the instance to use
+  # @return [Shakapacker::Instance] the instance that was set
+  # @api public
   def instance=(instance)
     @instance = instance
   end
 
+  # Returns the shared Shakapacker instance
+  #
+  # This instance is used by all module-level delegate methods. It provides
+  # access to configuration, compilation, manifest lookup, and more.
+  #
+  # @return [Shakapacker::Instance] the shared instance
+  # @api public
   def instance
     @instance ||= Shakapacker::Instance.new
   end
 
+  # Temporarily overrides NODE_ENV for the duration of the block
+  #
+  # This is useful when you need to perform operations with a specific NODE_ENV
+  # value without permanently changing the environment.
+  #
+  # @param env [String] the NODE_ENV value to use temporarily
+  # @yield the block to execute with the temporary NODE_ENV
+  # @return [Object] the return value of the block
+  # @example
+  #   Shakapacker.with_node_env("production") do
+  #     # This code runs with NODE_ENV=production
+  #     Shakapacker.compile
+  #   end
+  # @api public
   def with_node_env(env)
     original = ENV["NODE_ENV"]
     ENV["NODE_ENV"] = env
@@ -27,13 +91,32 @@ module Shakapacker
     ENV["NODE_ENV"] = original
   end
 
-  # Set NODE_ENV based on RAILS_ENV if not already set
-  # - development/test environments use their RAILS_ENV value
-  # - all other environments (production, staging, etc.) use "production" for webpack optimizations
+  # Sets NODE_ENV based on RAILS_ENV if not already set
+  #
+  # Environment mapping:
+  # - +development+ and +test+ environments use their RAILS_ENV value for NODE_ENV
+  # - All other environments (+production+, +staging+, etc.) use "production" for webpack optimizations
+  #
+  # This method is typically called automatically during Rails initialization.
+  #
+  # @return [String] the NODE_ENV value that was set
+  # @api private
   def ensure_node_env!
     ENV["NODE_ENV"] ||= DEV_TEST_ENVS.include?(ENV["RAILS_ENV"]) ? ENV["RAILS_ENV"] : "production"
   end
 
+  # Temporarily redirects Shakapacker logging to STDOUT
+  #
+  # This is useful for debugging or when you want to see compilation output
+  # in the console instead of the Rails log.
+  #
+  # @yield the block to execute with STDOUT logging
+  # @return [Object] the return value of the block
+  # @example
+  #   Shakapacker.ensure_log_goes_to_stdout do
+  #     Shakapacker.compile
+  #   end
+  # @api public
   def ensure_log_goes_to_stdout
     old_logger = Shakapacker.logger
     Shakapacker.logger = Logger.new(STDOUT)
@@ -42,8 +125,65 @@ module Shakapacker
     Shakapacker.logger = old_logger
   end
 
+  # @!method logger
+  #   Returns the logger instance used by Shakapacker
+  #   @return [Logger] the logger instance
+  #   @see Shakapacker::Instance#logger
+  # @!method logger=(logger)
+  #   Sets the logger instance used by Shakapacker
+  #   @param logger [Logger] the logger to use
+  #   @return [Logger] the logger that was set
+  #   @see Shakapacker::Instance#logger=
+  # @!method env
+  #   Returns the current Rails environment as an ActiveSupport::StringInquirer
+  #   @return [ActiveSupport::StringInquirer] the environment
+  #   @see Shakapacker::Instance#env
+  # @!method inlining_css?
+  #   Returns whether CSS inlining is enabled
+  #   @return [Boolean] true if CSS should be inlined
+  #   @see Shakapacker::Instance#inlining_css?
   delegate :logger, :logger=, :env, :inlining_css?, to: :instance
+
+  # @!method config
+  #   Returns the Shakapacker configuration object
+  #   @return [Shakapacker::Configuration] the configuration
+  #   @see Shakapacker::Instance#config
+  # @!method compiler
+  #   Returns the compiler instance for compiling assets
+  #   @return [Shakapacker::Compiler] the compiler
+  #   @see Shakapacker::Instance#compiler
+  # @!method manifest
+  #   Returns the manifest instance for looking up compiled assets
+  #   @return [Shakapacker::Manifest] the manifest
+  #   @see Shakapacker::Instance#manifest
+  # @!method commands
+  #   Returns the commands instance for build operations
+  #   @return [Shakapacker::Commands] the commands object
+  #   @see Shakapacker::Instance#commands
+  # @!method dev_server
+  #   Returns the dev server instance for querying server status
+  #   @return [Shakapacker::DevServer] the dev server
+  #   @see Shakapacker::Instance#dev_server
   delegate :config, :compiler, :manifest, :commands, :dev_server, to: :instance
+
+  # @!method bootstrap
+  #   Creates the default configuration files and directory structure
+  #   @return [void]
+  #   @see Shakapacker::Commands#bootstrap
+  # @!method clean(count = nil, age = nil)
+  #   Removes old compiled packs, keeping the most recent versions
+  #   @param count [Integer, nil] number of versions to keep per entry
+  #   @param age [Integer, nil] maximum age in seconds for packs to keep
+  #   @return [void]
+  #   @see Shakapacker::Commands#clean
+  # @!method clobber
+  #   Removes all compiled packs
+  #   @return [void]
+  #   @see Shakapacker::Commands#clobber
+  # @!method compile
+  #   Compiles all webpack/rspack packs
+  #   @return [Boolean] true if compilation succeeded
+  #   @see Shakapacker::Commands#compile
   delegate :bootstrap, :clean, :clobber, :compile, to: :commands
 end
 

data/lib/tasks/shakapacker/doctor.rake

@@ -11,7 +11,7 @@ namespace :shakapacker do
     • Required and optional npm dependencies
     • JavaScript transpiler (Babel, SWC, esbuild) configuration
     • CSS, CSS Modules, and stylesheet preprocessor setup
-    • Binstubs presence (shakapacker, shakapacker-dev-server, export-bundler-config)
+    • Binstubs presence (shakapacker, shakapacker-dev-server, shakapacker-config)
     • Version consistency between gem and npm package
     • Legacy Webpacker file detection
 

data/lib/tasks/shakapacker/export_bundler_config.rake

@@ -42,18 +42,18 @@ namespace :shakapacker do
     Note: When using 'rake', you must use '--' to separate rake options from task arguments.
           Example: rake shakapacker:export_bundler_config -- --doctor
 
-    The task automatically falls back to the gem version if bin/export-bundler-config
+    The task automatically falls back to the gem version if bin/shakapacker-config
     binstub is not installed. To install all binstubs, run: rails shakapacker:binstubs
   DESC
   task :export_bundler_config do
     # Try to use the binstub if it exists, otherwise use the gem's version
-    bin_path = Rails.root.join("bin/export-bundler-config")
+    bin_path = Rails.root.join("bin/shakapacker-config")
 
     unless File.exist?(bin_path)
       # Binstub not installed, use the gem's version directly
-      gem_bin_path = File.expand_path("../../install/bin/export-bundler-config", __dir__)
+      gem_bin_path = File.expand_path("../../install/bin/shakapacker-config", __dir__)
 
-      $stderr.puts "Note: bin/export-bundler-config binstub not found."
+      $stderr.puts "Note: bin/shakapacker-config binstub not found."
       $stderr.puts "Using gem version directly. To install the binstub, run: rake shakapacker:binstubs"
       $stderr.puts ""
 

data/package/config.ts

@@ -55,7 +55,6 @@ if (existsSync(configPath)) {
     const envAppConfig = appYmlObject[railsEnv]
 
     if (!envAppConfig) {
-      /* eslint no-console:0 */
       console.warn(
         `[SHAKAPACKER WARNING] Environment '${railsEnv}' not found in ${configPath}\n` +
           `Available environments: ${Object.keys(appYmlObject).join(", ")}\n` +

data/package/configExporter/buildValidator.ts

@@ -1,6 +1,6 @@
 import { spawn } from "child_process"
 import { existsSync } from "fs"
-import { resolve, relative, sep } from "path"
+import { resolve, relative } from "path"
 import { ResolvedBuildConfig, BuildValidationResult } from "./types"
 
 export interface ValidatorOptions {
@@ -173,7 +173,7 @@ export class BuildValidator {
    * @returns The resolved absolute path to the config file
    * @throws Error if the config file does not exist or is outside appRoot
    */
-  private validateConfigPath(
+  private static validateConfigPath(
     configFile: string,
     appRoot: string,
     buildName: string
@@ -222,7 +222,7 @@ export class BuildValidator {
     const isHMR =
       build.environment.WEBPACK_SERVE === "true" ||
       build.environment.HMR === "true"
-    const bundler = build.bundler
+    const { bundler } = build
 
     if (isHMR) {
       return this.validateHMRBuild(build, appRoot, bundler)
@@ -273,7 +273,7 @@ export class BuildValidator {
     // Add config file if specified
     if (build.configFile) {
       try {
-        const configPath = this.validateConfigPath(
+        const configPath = BuildValidator.validateConfigPath(
           build.configFile,
           appRoot,
           build.name
@@ -301,7 +301,7 @@ export class BuildValidator {
       args.push(...build.bundlerEnvArgs)
     }
 
-    return new Promise((resolve) => {
+    return new Promise((resolvePromise) => {
       const child = spawn(devServerBin, args, {
         cwd: appRoot,
         env: this.filterEnvironment(build.environment),
@@ -316,7 +316,7 @@ export class BuildValidator {
       const resolveOnce = (res: BuildValidationResult) => {
         if (!resolved) {
           resolved = true
-          resolve(res)
+          resolvePromise(res)
         }
       }
 
@@ -397,8 +397,8 @@ export class BuildValidator {
         })
       }
 
-      child.stdout?.on("data", (data) => processOutput(data))
-      child.stderr?.on("data", (data) => processOutput(data))
+      child.stdout?.on("data", (data: Buffer) => processOutput(data))
+      child.stderr?.on("data", (data: Buffer) => processOutput(data))
 
       child.on("exit", (code) => {
         clearTimeout(timeoutId)
@@ -428,7 +428,7 @@ export class BuildValidator {
 
         // Check for specific error codes and provide actionable guidance
         if ("code" in err) {
-          const code = (err as NodeJS.ErrnoException).code
+          const { code } = err as NodeJS.ErrnoException
           if (code === "ENOENT") {
             errorMessage += `. Binary not found. Install with: npm install -D ${devServerCmd}`
           } else if (code === "EMFILE" || code === "ENFILE") {
@@ -484,7 +484,7 @@ export class BuildValidator {
     // Add config file if specified
     if (build.configFile) {
       try {
-        const configPath = this.validateConfigPath(
+        const configPath = BuildValidator.validateConfigPath(
           build.configFile,
           appRoot,
           build.name
@@ -515,7 +515,7 @@ export class BuildValidator {
     // Add --json for structured output (helps parse errors)
     args.push("--json")
 
-    return new Promise((resolve) => {
+    return new Promise((resolvePromise) => {
       const child = spawn(bundlerBin, args, {
         cwd: appRoot,
         env: this.filterEnvironment(build.environment),
@@ -534,7 +534,7 @@ export class BuildValidator {
           `Timeout: ${bundler} did not complete within ${this.options.timeout}ms.`
         )
         child.kill("SIGTERM")
-        resolve(result)
+        resolvePromise(result)
       }, this.options.timeout)
 
       child.stdout?.on("data", (data: Buffer) => {
@@ -603,7 +603,7 @@ export class BuildValidator {
 
         // Parse JSON output
         try {
-          const jsonOutput: WebpackJsonOutput = JSON.parse(stdoutData)
+          const jsonOutput = JSON.parse(stdoutData) as WebpackJsonOutput
 
           // Extract output path if available
           if (jsonOutput.outputPath) {
@@ -613,10 +613,22 @@ export class BuildValidator {
           // Check for errors in webpack/rspack JSON output
           if (jsonOutput.errors && jsonOutput.errors.length > 0) {
             jsonOutput.errors.forEach((error) => {
-              const errorMsg =
-                typeof error === "string"
-                  ? error
-                  : error.message || String(error)
+              let errorMsg: string
+              if (typeof error === "string") {
+                errorMsg = error
+              } else if (error.message) {
+                errorMsg = error.message
+              } else {
+                // Attempt to extract useful info from malformed error using all enumerable props
+                try {
+                  errorMsg = JSON.stringify(
+                    error,
+                    Object.getOwnPropertyNames(error)
+                  )
+                } catch {
+                  errorMsg = "[Error object with no message]"
+                }
+              }
               result.errors.push(errorMsg)
               // Also add to output for visibility
               if (!this.options.verbose) {
@@ -628,10 +640,22 @@ export class BuildValidator {
           // Check for warnings
           if (jsonOutput.warnings && jsonOutput.warnings.length > 0) {
             jsonOutput.warnings.forEach((warning) => {
-              const warningMsg =
-                typeof warning === "string"
-                  ? warning
-                  : warning.message || String(warning)
+              let warningMsg: string
+              if (typeof warning === "string") {
+                warningMsg = warning
+              } else if (warning.message) {
+                warningMsg = warning.message
+              } else {
+                // Attempt to extract useful info from malformed warning using all enumerable props
+                try {
+                  warningMsg = JSON.stringify(
+                    warning,
+                    Object.getOwnPropertyNames(warning)
+                  )
+                } catch {
+                  warningMsg = "[Warning object with no message]"
+                }
+              }
               result.warnings.push(warningMsg)
             })
           }
@@ -683,7 +707,7 @@ export class BuildValidator {
           result.output.push(stderrData)
         }
 
-        resolve(result)
+        resolvePromise(result)
       })
 
       child.on("error", (err) => {
@@ -693,7 +717,7 @@ export class BuildValidator {
 
         // Check for specific error codes and provide actionable guidance
         if ("code" in err) {
-          const code = (err as NodeJS.ErrnoException).code
+          const { code } = err as NodeJS.ErrnoException
           if (code === "ENOENT") {
             errorMessage += `. Binary not found. Install with: npm install -D ${bundler}`
           } else if (code === "EMFILE" || code === "ENFILE") {
@@ -704,7 +728,7 @@ export class BuildValidator {
         }
 
         result.errors.push(errorMessage)
-        resolve(result)
+        resolvePromise(result)
       })
     })
   }
@@ -776,19 +800,19 @@ export class BuildValidator {
   formatResults(results: BuildValidationResult[]): string {
     const lines: string[] = []
 
-    lines.push("\n" + "=".repeat(80))
+    lines.push(`\n${"=".repeat(80)}`)
     lines.push("🔍 Build Validation Results")
-    lines.push("=".repeat(80) + "\n")
+    lines.push(`${"=".repeat(80)}\n`)
 
-    let totalBuilds = results.length
+    const totalBuilds = results.length
     let successCount = 0
     let failureCount = 0
 
     results.forEach((result) => {
       if (result.success) {
-        successCount++
+        successCount += 1
       } else {
-        failureCount++
+        failureCount += 1
       }
 
       const icon = result.success ? "✅" : "❌"