Merge pull request #78 from infertux/nix-support

Add support for building Bashcov with the Nix package manager

.github/workflows/ci.yml

@@ -76,3 +76,15 @@ jobs:
         id: yard
         run: |
           bundle exec yard stats --list-undoc
+  nix:
+    runs-on: ubuntu-latest
+    # Don't fail the build if this job fails
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v3
+      - uses: cachix/install-nix-action@v22
+        with:
+          extra_nix_config: |
+            system-features = benchmark big-parallel kvm nixos-test uid-range
+      - name: run flake checks
+        run: nix flake check -L

.github/workflows/deps.yml

@@ -0,0 +1,35 @@
+name: Update Nix dependencies
+
+on:
+  schedule:
+    # Sunday and Wednesday
+    - cron: '42 4 * * 0,3'
+  workflow_dispatch:
+
+jobs:
+  update-deps-conservative:
+    runs-on: ubuntu-latest
+    permissions:
+      # So that `create-pull-request` can... create a pull request :)
+      # https://github.com/peter-evans/create-pull-request#action-inputs
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v3
+      - uses: cachix/install-nix-action@v22
+        with:
+          extra_nix_config: |
+            system-features = benchmark big-parallel kvm nixos-test uid-range
+      - name: update lockfiles
+        run: nix run '.#devshell' -- update-deps-conservative
+      - name: create PR
+        uses: peter-evans/create-pull-request@v5
+        with:
+          branch: create-pull-request/update-nix-deps
+          title: '[create-pull-request] Update Nix dependencies'
+          body: |
+            Update Nix dependencies in `Gemfile.nix.lock` and `gemset.nix`.
+
+            Auto-generated by [create-pull-request][1].
+
+            [1]: https://github.com/peter-evans/create-pull-request

.gitignore

@@ -17,3 +17,11 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+
+# Nix output links
+result
+result-*
+repl-result-*
+
+# Bundler-installed gems
+/vendor/

.rubocop.yml

@@ -5,6 +5,26 @@ require:
 AllCops:
   TargetRubyVersion: 3.0
   NewCops: enable
+  # Ignore files ignored by Git.  Improved version of the template shown here:
+  # https://docs.rubocop.org/rubocop/configuration.html#pre-processing
+  # Properly handles symlinks-to-directories, which `git status --ignored
+  # --porcelain` displays without a trailing slash.
+  Exclude:
+    <% git_ignored_file_status = `git status --ignored --porcelain 2>/dev/null` %>
+    <% if $? == 0 %>
+      <% git_ignored_file_status.each_line(chomp: true).grep(/^!! /).map { |p| p.sub(/^!! /, '') }.each do |path| %>
+        <% if File.directory?(path) && ! path.end_with?('/') %>
+    - <%= path + '/**/*' %>
+        <% else %>
+    - <%= path.sub(/\/$/, '/**/*') %>
+        <% end %>
+      <% end %>
+    <% else %>
+    - 'vendor/**/*'
+    - 'result/**/*'
+    - 'result-*/**/*'
+    - 'repl-result-*/**/*'
+    <% end %>
 
 Metrics:
   Enabled: false

CHANGELOG.md

@@ -1,6 +1,6 @@
 ## Unreleased ([changes](https://github.com/infertux/bashcov/compare/v3.1.3...master))
 
-  * TBD
+  * [FEATURE] Support building Bashcov with [the Nix package manager](https://nixos.org) (#78)
 
 ## v3.1.3, 2024-08-29 ([changes](https://github.com/infertux/bashcov/compare/v3.1.2...v3.1.3))
 

Gemfile.nix.lock

@@ -0,0 +1,132 @@
+PATH
+  remote: .
+  specs:
+    bashcov (3.1.2)
+      simplecov (~> 0.22.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    aruba (2.2.0)
+      bundler (>= 1.17, < 3.0)
+      contracts (>= 0.16.0, < 0.18.0)
+      cucumber (>= 8.0, < 10.0)
+      rspec-expectations (~> 3.4)
+      thor (~> 1.0)
+    ast (2.4.2)
+    bigdecimal (3.1.7)
+    builder (3.2.4)
+    bundler-audit (0.9.1)
+      bundler (>= 1.2.0, < 3)
+      thor (~> 1.0)
+    contracts (0.17)
+    cucumber (9.2.0)
+      builder (~> 3.2)
+      cucumber-ci-environment (> 9, < 11)
+      cucumber-core (> 13, < 14)
+      cucumber-cucumber-expressions (~> 17.0)
+      cucumber-gherkin (> 24, < 28)
+      cucumber-html-formatter (> 20.3, < 22)
+      cucumber-messages (> 19, < 25)
+      diff-lcs (~> 1.5)
+      mini_mime (~> 1.1)
+      multi_test (~> 1.1)
+      sys-uname (~> 1.2)
+    cucumber-ci-environment (10.0.1)
+    cucumber-core (13.0.2)
+      cucumber-gherkin (>= 27, < 28)
+      cucumber-messages (>= 20, < 23)
+      cucumber-tag-expressions (> 5, < 7)
+    cucumber-cucumber-expressions (17.1.0)
+      bigdecimal
+    cucumber-gherkin (27.0.0)
+      cucumber-messages (>= 19.1.4, < 23)
+    cucumber-html-formatter (21.3.1)
+      cucumber-messages (> 19, < 25)
+    cucumber-messages (22.0.0)
+    cucumber-tag-expressions (6.1.0)
+    diff-lcs (1.5.1)
+    docile (1.4.0)
+    ffi (1.16.3)
+    json (2.7.2)
+    language_server-protocol (3.17.0.3)
+    mini_mime (1.1.5)
+    multi_test (1.1.0)
+    parallel (1.24.0)
+    parser (3.3.0.5)
+      ast (~> 2.4.1)
+      racc
+    racc (1.7.3)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    regexp_parser (2.9.0)
+    rexml (3.2.6)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (1.63.2)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.31.2)
+      parser (>= 3.3.0.4)
+    rubocop-capybara (2.20.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.25.1)
+      rubocop (~> 1.41)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.29.1)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.28.3)
+      rubocop (~> 1.40)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    sys-uname (1.2.3)
+      ffi (~> 1.1)
+    thor (1.3.1)
+    unicode-display_width (2.5.0)
+    yard (0.9.36)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  aruba
+  bashcov!
+  bundler-audit
+  cucumber
+  rake
+  rspec
+  rubocop
+  rubocop-rake
+  rubocop-rspec
+  yard
+
+BUNDLED WITH
+   2.4.10

HACKING.md

@@ -0,0 +1,166 @@
+# Hacking on Bashcov
+
+[Nix development shell]: #entering-the-nix-development-shell
+[`Gemfile.nix.lock`]: ./Gemfile.nix.lock
+[`gemset.nix`]: ./gemset.nix
+[`bashcov.gemspec`]: ./bashcov.gemspec
+
+## Nix flake usage
+
+This project supplies a [`flake.nix`](./flake.nix) file defining a Nix
+flake[^nix-flakes] that makes it possible to build, test, run, and hack on
+Bashcov using the [Nix package manager](https://nixos.org)
+
+[^nix-flakes]: See the [NixOS wiki](https://nixos.wiki/wiki/Flakes) and the
+               [`nix flake` page in the Nix package manager reference manual](https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html)
+               for background on Nix flakes.
+
+This Nix flake defines three important important outputs:
+
+1. A [Nix package for Bashcov](#building-the-bashcov-package),
+2. A [Nix flake check](#nix-flake-checks) (test) that runs Bashcov's
+   unit and feature tests,
+3. A [Nix application](#running-the-nix-application),[^app] and
+4. A [Nix development shell],[^devshell].
+
+[^devshell]: Based on the [`numtide/devshell`](https://github.com/numtide/devshell) project.
+[^app]: Runnable with `nix run`.
+
+In order to work on the Bashcov project's Nix features,
+you'll need to [install the Nix package manager](https://nixos.org/download.html) and
+[ensure that the `flakes` and `nix-command` experimental features are enabled](https://nixos.wiki/wiki/Flakes#Enable_flakes).
+
+### Building the Bashcov package
+
+To build the Bashcov package exposed by this flake, run the
+following command:[^verbose-output]
+
+[^verbose-output]: Note that the `-L` flag can be omitted for terser output.
+
+```shell-session
+$ nix build -L '.#'
+```
+
+Or:
+
+```shell-session
+$ nix build -L '.#bashcov'
+```
+
+These two forms are functionally equivalent because the
+Bashcov package is the default package.
+
+In addition to building the package, `nix build` will place a symbolic link to
+its output path at `./result` (`ls -lAR ./result/`, `tree ./result/`, or
+similar to see what the package contains).
+
+### Nix flake checks
+
+This project includes a test of Bashcov's functionality and features, exposed
+as a Nix flake check.  In essence, this runs the Bashcov test suite, but inside
+the Nix build environment[^nix-builder-execution] (which may be
+sandboxed[^nix-sandbox]).
+
+[^nix-builder-execution]: The Nix build environment is described [here](https://nixos.org/manual/nix/stable/language/derivations#builder-execution).
+[^nix-sandbox]: The Nix sandbox is described [here](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-sandbox).
+
+This project also includes a test that Nix source files are properly
+formatted.[^treefmt-nix-check]
+
+[^treefmt-nix-check]: Defined by [`treefmt-nix`](https://github.com/numtide/treefmt-nix#flakes).
+
+#### Running Nix flake checks
+
+To run Nix flake checks, execute the following command:[^verbose-output]
+
+```shell-session
+$ nix flake check -L
+```
+
+If a check fails, `nix` will print a diagnostic message and exit with nonzero
+status.
+
+##### Running a check for a specific system
+
+Running `nix flake check` will execute Nix flake checks for all supported
+systems.[^supported-systems]  To run a check for a particular system, instead
+use the `nix build` command.  For instance, to execute the Bashcov unit and
+feature tests with Nix on the `x86_64-linux` system, run:[^verbose-output]
+
+```shell-session
+$ nix build -L '.#checks.x86_64-linux.bashcov'
+```
+
+[^supported-systems]: Run `nix flake show` to view flake outputs namespaced by
+                      all supported systems.
+
+### Running the Nix application
+
+To run Bashcov itself:
+
+```shell-session
+$ nix run '.#' -- <args>
+```
+
+To run commands from [the Nix development shell](#entering-the-nix-development-shell)
+but without entering the shell:
+
+```shell-session
+$ nix run '.#devshell' -- <command> <args>
+```
+
+For instance, to run [the `update-deps` shell command](#summary-of-available-commands):
+
+```shell-session
+$ nix run '.#devshell' -- update-deps
+```
+
+### Entering the Nix development shell
+
+To enter the Nix development shell, run the following command:
+
+```shell-session
+$ nix develop
+```
+
+You will be presented with a menu of commands available within the development
+shell.
+
+#### Summary of available commands
+
+- `fmt`: format all Nix code in this project using
+  [`alejandra`](https://github.com/kamadorueda/alejandra).
+- `bundix`: tool for managing Nix <=> Ruby integration assets (Bundix lives
+  [here](https://github.com/nix-community/bundix)).
+- `update-deps`: update [the Nix-specific lockfile][`Gemfile.nix.lock`] and
+  [Nix gemset][`gemset.nix`].
+- `update-deps-conservative`: update [the Nix-specific lockfile][`Gemfile.nix.lock`]
+  and [Nix gemset][`gemset.nix`] if (and only if) `nix build` fails _without_
+  updates to those assets **and** `nix build` succeeds _with_ updates to them.
+
+### Maintenance of Nix assets
+
+The Bashcov Nix package depends on [`nixpkgs`'s Ruby
+integration](https://nixos.org/manual/nixpkgs/stable/#developing-with-ruby);
+specifically, it uses the `bundlerEnv` function to create an environment with
+all of Bashcov's Ruby gem dependencies present.  `bundlerEnv` requires a
+Bundler lockfile (here, [`Gemfile.nix.lock`]) and a Nix-specific [`gemset.nix`]
+that acts as a sort of translation layer between Bundler and Nix.
+
+Both of these files must be updated from time to time in order to reflect
+changes in [`bashcov.gemspec`], including certain changes to Bashcov itself
+(e.g. version bumps).
+
+> **Note**
+> If [`bashcov.gemspec`] is updated without updating the Bundler lockfile and
+> [`gemset.nix`], the Bashcov Nix package will fail to build.
+
+The [Nix development shell] includes two convenience commands for managing
+these assets:
+
+- `update-deps` unconditionally updates [`Gemfile.nix.lock`] with
+  [`bundle lock`](https://bundler.io/v2.4/man/bundle-lock.1.html), then updates
+  [`gemset.nix`] to reflect any changes to the Bundler lockfile.
+- `update-deps-conservative` does the same, but if (and only if) doing so fixes
+  failures running `nix build`.  That is, it updates the assets if it looks
+  like problems with those assets have broken the Bashcov Nix package.