Add ability to choose a different formatter

.github/workflows/test.yml

@@ -33,6 +33,9 @@ jobs:
     - name: Install pandoc
       run: rush get pandoc
 
+    - name: Install shfmt
+      run: rush get shfmt
+
     # libyaml needed for Ruby's YAML library
     - name: Install OS dependencies
       run: sudo apt-get -y install libyaml-dev

examples/render-mandoc/docs/download.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.2
 .\"
-.TH "download" "1" "July 2025" "Version 0.1.0" "Sample application"
+.TH "download" "1" "August 2025" "Version 0.1.0" "Sample application"
 .SH NAME
 \f[B]download\f[R] \- Sample application
 .SH SYNOPSIS

examples/render-mandoc/docs/download.md

@@ -1,6 +1,6 @@
 % download(1) Version 0.1.0 | Sample application
 % Lana Lang
-% July 2025
+% August 2025
 
 NAME
 ==================================================

lib/bashly.rb

@@ -22,7 +22,7 @@ module Bashly
   module Script
     autoloads 'bashly/script', %i[
       Argument Base CatchAll Command Dependency EnvironmentVariable Flag
-      Variable Wrapper
+      Formatter Variable Wrapper
     ]
 
     module Introspection

lib/bashly/extensions/string.rb

@@ -44,8 +44,8 @@ def wrap(length = 80)
     end * "\n"
   end
 
-  def lint
-    gsub(/\s+\n/m, "\n\n").lines.grep_v(/^\s*##/).join
+  def remove_private_comments
+    lines.grep_v(/^\s*##/).join
   end
 
   def remove_front_matter

lib/bashly/libraries/settings/settings.yml

@@ -41,16 +41,26 @@ partials_extension: sh
 #-------------------------------------------------------------------------------
 
 # Configure the bash options that will be added to the initialize function:
-# strict: true       Bash strict mode (set -euo pipefail)
-# strict: false      Only exit on errors (set -e)
-# strict: ''         Do not add any 'set' directive
-# strict: <string>   Add any other custom 'set' directive
+# strict: true       # Bash strict mode (set -euo pipefail)
+# strict: false      # Only exit on errors (set -e)
+# strict: ''         # Do not add any 'set' directive
+# strict: <string>   # Add any other custom 'set' directive
 strict: false
 
 # When true, the generated script will use tab indentation instead of spaces
 # (every 2 leading spaces will be converted to a tab character)
 tab_indent: false
 
+# Choose a post-processor for the generated script:
+# formatter: internal     # Use Bashly's internal formatter (compacts newlines)
+# formatter: external     # Run the external command `shfmt --case-indent --indent 2`
+# formatter: none         # Disable formatting entirely
+# formatter: <string>     # Use a custom shell command to format the script.
+#                         # The command will receive the script via stdin and
+#                         # must output the result to stdout.
+#                         # Example: shfmt --minify
+formatter: internal
+
 
 #-------------------------------------------------------------------------------
 # INTERFACE OPTIONS
@@ -100,10 +110,10 @@ env: development
 
 # Tweak the script output by enabling or disabling some script output.
 # These options accept one of the following strings:
-# - production      render this feature only when env == production
-# - development     render this feature only when env == development
-# - always          render this feature in any environment
-# - never           do not render this feature
+# - production      # render this feature only when env == production
+# - development     # render this feature only when env == development
+# - always          # render this feature in any environment
+# - never           # do not render this feature
 enable_header_comment: always
 enable_bash3_bouncer: always
 enable_view_markers: development

lib/bashly/script/formatter.rb

@@ -0,0 +1,44 @@
+require 'open3'
+require 'shellwords'
+
+module Bashly
+  module Script
+    class Formatter
+      attr_reader :script, :mode
+
+      def initialize(script, mode: nil)
+        @script = script
+        @mode = mode&.to_s || 'internal'
+      end
+
+      def formatted_script
+        case mode
+        when 'internal' then script.gsub(/\s+\n/m, "\n\n")
+        when 'external' then shfmt_result
+        when 'none' then script
+        else custom_formatter_result mode
+        end
+      end
+
+    private
+
+      def shfmt_result
+        custom_formatter_result %w[shfmt --case-indent --indent 2]
+      end
+
+      def custom_formatter_result(command)
+        command = Shellwords.split command if command.is_a? String
+
+        begin
+          output, error, status = Open3.capture3(*command, stdin_data: script)
+        rescue Errno::ENOENT
+          raise Error, "Command not found: g`#{command.first}`"
+        end
+
+        raise Error, "Failed running g`#{Shellwords.join command}`:\n\n#{error}" unless status.success?
+
+        output
+      end
+    end
+  end
+end

lib/bashly/script/wrapper.rb

@@ -23,7 +23,13 @@ def base_code
           [header, body]
         end
 
-        result.join("\n").lint
+        clean_code result.join("\n")
+      end
+
+      def clean_code(script)
+        result = script.remove_private_comments
+        formatter = Formatter.new result, mode: Settings.formatter
+        formatter.formatted_script
       end
 
       def header

lib/bashly/settings.rb

@@ -15,6 +15,7 @@ class << self
         :enable_inspect_args,
         :enable_sourcing,
         :enable_view_markers,
+        :formatter,
         :function_names,
         :lib_dir,
         :partials_extension,
@@ -86,6 +87,10 @@ def env=(value)
         @env = value&.to_sym
       end
 
+      def formatter
+        @formatter ||= get :formatter
+      end
+
       def full_lib_dir
         "#{source_dir}/#{lib_dir}"
       end

schemas/settings.json

@@ -213,6 +213,25 @@
       ],
       "default": "development"
     },
+    "formatter": {
+      "title": "formatter",
+      "description": "Choose how to post-process the generated script\nhttps://bashly.dev/usage/settings/#formatter",
+      "anyOf": [
+        {
+          "type": "string",
+          "enum": [
+            "internal",
+            "none",
+            "external"
+          ]
+        },
+        {
+          "type": "string",
+          "minLength": 1
+        }
+      ],
+      "default": ":internal"
+    },
     "partials_extension": {
       "title": "partials extension",
       "description": "The extension to use when reading/writing partial script snippets\nhttps://bashly.dev/usage/settings/#partials_extension",

spec/approvals/examples/render-mandoc

@@ -44,4 +44,4 @@ ISSUE TRACKER
 AUTHORS
        Lana Lang.
 
-Version 0.1.0                      July 2025                       download(1)
+Version 0.1.0                     August 2025                      download(1)

spec/approvals/examples/stacktrace

@@ -51,5 +51,5 @@ Examples:
 
 Stack trace:
 	from ./download:15 in `root_command`
-	from ./download:260 in `run`
-	from ./download:266 in `main`
+	from ./download:259 in `run`
+	from ./download:265 in `main`

spec/approvals/formatter/error-failure

@@ -0,0 +1 @@
+#<Bashly::Error:"Failed running g`shfmt --diff`:\n\n">

spec/approvals/formatter/error-not-found

@@ -0,0 +1 @@
+#<Bashly::Error: Command not found: g`my_formatter`>

spec/approvals/formatter/internal

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+funk() {
+  cat <<EOF
+start multiline heredoc test
+
+end multiline heredoc test
+EOF
+
+  echo "unnecessary multiline test"
+
+  echo "unnecessary multiline test complete"
+        echo "rogue indentation"
+}

spec/approvals/formatter/shfmt

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+
+funk() {
+  cat <<EOF
+start multiline heredoc test
+
+
+
+end multiline heredoc test
+EOF
+
+  echo "unnecessary multiline test"
+
+  echo "unnecessary multiline test complete"
+  echo "rogue indentation"
+}

spec/approvals/formatter/shfmt-custom

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+funk()
+{
+	cat <<EOF
+start multiline heredoc test
+
+
+
+end multiline heredoc test
+EOF
+
+	echo "unnecessary multiline test"
+
+	echo "unnecessary multiline test complete"
+	echo "rogue indentation"
+}

spec/bashly/extensions/string_spec.rb

@@ -125,21 +125,11 @@
     end
   end
 
-  describe '#lint' do
-    context 'with a string that contains multiple consecutive newlines' do
-      subject { "one\n  two\n  \n    three\n \n \nfour\n\n\n\n" }
+  describe '#remove_private_comments' do
+    subject { "this is important\n## SECRET\n  ## ANOTHER SECRET\n  also important\n" }
 
-      it 'replaces two or more newlines with two newlines' do
-        expect(subject.lint).to eq "one\n  two\n\n    three\n\nfour\n\n"
-      end
-    end
-
-    context 'with a string that contains double-hash comments' do
-      subject { "this is important\n## SECRET\n  ## ANOTHER SECRET\n  also important\n" }
-
-      it 'removes these comments' do
-        expect(subject.lint).to eq "this is important\n  also important\n"
-      end
+    it 'removes these comments' do
+      expect(subject.remove_private_comments).to eq "this is important\n  also important\n"
     end
   end
 

spec/bashly/script/formatter_spec.rb

@@ -0,0 +1,53 @@
+describe Script::Formatter do
+  subject { described_class.new script, mode: mode }
+
+  let(:script) { File.read "spec/fixtures/formatter/#{script_id}.sh" }
+  let(:script_id) { :simple }
+  let(:mode) { nil }
+
+  describe '#formatted_script' do
+    it 'formats the script using the internal formatter' do
+      expect(subject.formatted_script).to match_approval 'formatter/internal'
+    end
+
+    context 'with mode: none' do
+      let(:mode) { 'none' }
+
+      it 'returns the original script' do
+        expect(subject.formatted_script).to eq script
+      end
+    end
+
+    context 'with mode: external' do
+      let(:mode) { 'external' }
+
+      it 'uses shfmt to format the script' do
+        expect(subject.formatted_script).to match_approval 'formatter/shfmt'
+      end
+    end
+
+    context 'with mode: shfmt (string)' do
+      let(:mode) { 'shfmt --func-next-line' }
+
+      it 'uses the given command shfmt to format the script' do
+        expect(subject.formatted_script).to match_approval 'formatter/shfmt-custom'
+      end
+    end
+
+    context 'when the external command does not exist' do
+      let(:mode) { 'my_formatter' }
+
+      it 'raises a Bashly::Error' do
+        expect { subject.formatted_script }.to raise_approval 'formatter/error-not-found'
+      end
+    end
+
+    context 'when the external command fails' do
+      let(:mode) { 'shfmt --diff' }
+
+      it 'raises a a Bashly::Error' do
+        expect { subject.formatted_script }.to raise_approval 'formatter/error-failure'
+      end
+    end
+  end
+end

spec/fixtures/formatter/simple.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+funk() {
+  cat <<EOF
+start multiline heredoc test
+
+
+
+end multiline heredoc test
+EOF
+
+  echo "unnecessary multiline test"
+
+
+
+  echo "unnecessary multiline test complete"
+        echo "rogue indentation"
+}

support/schema/settings.yml

@@ -181,6 +181,20 @@ properties:
     type: string
     enum: *feature_toggles
     default: development
+  formatter:
+    title: formatter
+    description: |-
+      Choose how to post-process the generated script
+      https://bashly.dev/usage/settings/#formatter
+    anyOf:
+      - type: string
+        enum:
+          - internal
+          - none
+          - external
+      - type: string
+        minLength: 1
+    default: :internal
   partials_extension:
     title: partials extension
     description: |-