package_json 0.1.0

data/README.md

@@ -0,0 +1,284 @@
+# PackageJson
+
+The missing gem for managing `package.json` files, without having to know about
+package managers (mostly).
+
+It provides an interface for easily modifying the properties of `package.json`
+files, along with a "middle-level" abstraction over JavaScript package mangers
+to make it easy to manage dependencies without needing to know the specifics of
+the underlying package manager (and potentially without even knowing the manager
+itself!).
+
+This is _not_ meant to provide the exact same functionality and behaviour
+regardless of what package manager is being used, but rather make it easier to
+perform common general tasks that are supported by all package managers like
+adding new dependencies, installing existing ones, and running scripts without
+having to know the actual command a specific package manager requires for that
+action (and other such nuances).
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add package_json
+
+If bundler is not being used to manage dependencies, install the gem by
+executing:
+
+    $ gem install package_json
+
+## Usage
+
+```ruby
+# represents $PWD/package.json, creating it if it does not exist
+package_json = PackageJson.new
+
+# adds eslint, eslint-plugin-prettier, and prettier as development dependencies
+package_json.manager.add(%w[eslint prettier], :dev)
+
+# adds the "lint" and "format" scripts, preserving any existing scripts
+package_json.merge! do |pj|
+  {
+    "scripts" => pj.fetch("scripts", {}).merge({
+      "lint" => "eslint . --ext js",
+      "format" => "prettier --check ."
+    })
+  }
+end
+
+# deletes the "babel" property, if it exists
+package_json.delete!("babel")
+
+# runs the "lint" script with the "--fix" argument
+package_json.manager.run("lint", ["--fix"])
+```
+
+The `PackageJson` class represents a `package.json` on disk within a directory;
+because it is expected that the `package.json` might be changed by external
+sources such as package managers, `PackageJson` reads and writes to and from the
+`package.json` as needed rather than representing it in memory.
+
+If you expect the `package.json` to already exist, you can use `read` instead
+which will raise an error instead of implicitly creating the file if it doesn't
+exist.
+
+A `PackageJson` also comes with a `manager` that can be used to manage
+dependencies and run scripts.
+
+### Specifying a package manager
+
+You can specify which package manager should be used with the
+[`packageManager`](https://nodejs.org/api/packages.html#packagemanager) property
+in the `package.json`.
+
+> **Note**
+>
+> Only the name of the package manager is used; the version (if present) is
+> _not_ checked, nor is [`codepack`](https://nodejs.org/api/corepack.html) used
+> to ensure that the package manager is installed.
+>
+> The manager will be invoked by its name in the directory of the
+> `package.json`, and it is up to the developer to ensure that results in the
+> desired package manager actually running.
+
+If the `packageManager` property is not present, then the fallback manager will
+be used; this defaults to the value of the `PACKAGE_JSON_FALLBACK_MANAGER`
+environment variable or otherwise `npm`. You can also provide a specific
+fallback manager:
+
+```ruby
+PackageJson.read(fallback_manager: :pnpm)
+PackageJson.new(fallback_manager: :yarn_classic)
+```
+
+Supported package managers are `:npm`, `:yarn_berry`, `:yarn_classic`, `:pnpm`,
+and `:bun`.
+
+If the `package.json` does not exist, then the `packageManager` property will be
+included based on this value, but it will _not_ be updated if the file already
+exists without the property.
+
+Managers are provided a reference to the `PackageJson` when they're initialized,
+are run in the same directory as that `PackageJson`.
+
+### Using the package manager
+
+Each package manager supports a set of common methods which are covered below.
+Unless otherwise noted for a particular method, each method:
+
+- Behaves like `system`, returning either `true`, `false`, or `nil` based on if
+  the package manager exited with a non-zero error code; each method has a
+  bang-equivalent if you wish an exception to be thrown instead
+- Does not attempt to capture or intercept the output; using `Kernel.system`
+  under the hood, output is sent directly to `stdout` and `stderr`
+- Will run in the directory of the `package.json`; for methods that generate
+  native commands, it is up to the caller to ensure the working directory is
+  correct
+
+#### Get the version of the package manager
+
+```ruby
+package_json.manager.version
+```
+
+This is suitable for checking that the package manager is actually available
+before performing other operations. Unlike other non-bang methods, this will
+error if the underlying command exits with a non-zero code.
+
+#### Installing dependencies
+
+```ruby
+# install all dependencies
+package_json.manager.install
+
+# install all dependencies, erroring if the lockfile is outdated
+package_json.manager.install(frozen: true)
+```
+
+| Option   | Description                              |
+| -------- | ---------------------------------------- |
+| `frozen` | Fail if the lockfile needs to be updated |
+
+#### Generating the `install` command for native scripts and advanced calls
+
+```ruby
+# returns an array of strings that make up the desired operation
+native_install_command = package_json.manager.native_install_command
+
+# runs the command with extra environment variables
+Kernel.system({ "HELLO" => "WORLD" }, *native_install_command)
+
+append_to_file "bin/ci-run" do
+  <<~CMD
+    echo "* ******************************************************"
+    echo "* Installing JS dependencies"
+    echo "* ******************************************************"
+    #{native_install_command.join(" ")}
+  CMD
+end
+```
+
+| Option   | Description                              |
+| -------- | ---------------------------------------- |
+| `frozen` | Fail if the lockfile needs to be updated |
+
+#### Adding dependencies
+
+```ruby
+# adds axios as a production dependency
+package_json.manager.add(["axios"])
+
+# adds eslint and prettier as dev dependencies
+package_json.manager.add(["eslint", "prettier"], type: :dev)
+
+# adds dotenv-webpack v6 as a production dependency
+package_json.manager.add(["dotenv-webpack@^6"])
+```
+
+| Option | Description                                                                                 |
+| ------ | ------------------------------------------------------------------------------------------- |
+| `type` | The type to add the dependencies as; either `:production` (default), `:dev`, or `:optional` |
+
+#### Removing dependencies
+
+```ruby
+# removes the axios package
+package_json.manager.remove(["axios"])
+```
+
+#### Run a script
+
+```ruby
+# runs the "test" script
+package_json.manager.run("test")
+
+# runs the "test" script, passing it "--coverage path/to/my/test.js" as the argument
+package_json.manager.run("test", ["--coverage", "path/to/my/test.js"])
+
+# runs the "lint" script, passing it "--fix" as the argument and telling the package manager to be silent
+package_json.manager.run("lint", ["--fix"], silent: true)
+```
+
+| Option   | Description                              |
+| -------- | ---------------------------------------- |
+| `silent` | Suppress output from the package manager |
+
+#### Generating a `run` command for native scripts and advanced calls
+
+```ruby
+native_run_command = package_json.manager.native_run_command("test", ["--coverage"])
+
+# runs the command with extra environment variables
+Kernel.system({ "HELLO" => "WORLD" }, *native_run_command)
+
+append_to_file "bin/ci-run" do
+  <<~CMD
+    echo "* ******************************************************"
+    echo "* Running JS tests"
+    echo "* ******************************************************"
+    #{native_run_command.join(" ")}
+  CMD
+end
+```
+
+| Option   | Description                              |
+| -------- | ---------------------------------------- |
+| `silent` | Suppress output from the package manager |
+
+#### Generating a `exec` command for native scripts and advanced calls
+
+```ruby
+native_exec_command = package_json.manager.native_exec_command("webpack", ["serve"])
+
+# runs the command with extra environment variables
+Kernel.system({ "HELLO" => "WORLD" }, *native_exec_command)
+
+append_to_file "bin/webpack-webpack" do
+  <<~CMD
+    echo "* ******************************************************"
+    echo "* Serving assets via webpack
+    echo "* ******************************************************"
+    #{native_exec_command.join(" ")}
+  CMD
+end
+```
+
+> **Note**
+>
+> Since Yarn Classic doesn't provide a native `exec` command, `yarn bin` is used
+> instead to identify where the package command should be within `node_modules`.
+>
+> For other package managers, their native `exec` command is used with the flags
+> necessary to enforce the package command is only executed if the package is
+> installed locally.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/[USERNAME]/package_json. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to adhere
+to the
+[code of conduct](https://github.com/[USERNAME]/package_json/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the PackageJson project's codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/[USERNAME]/package_json/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/package_json/managers/base.rb

@@ -0,0 +1,118 @@
+class PackageJson
+  module Managers
+    class Base
+      # @return [String] the binary to invoke for running the package manager
+      attr_reader :binary
+
+      def initialize(package_json, binary_name:)
+        # @type [PackageJson]
+        @package_json = package_json
+        # @type [String]
+        @binary = binary_name
+      end
+
+      def version
+        require "open3"
+
+        command = "#{binary} --version"
+        stdout, stderr, status = Open3.capture3(command, chdir: @package_json.directory)
+
+        unless status.success?
+          raise PackageJson::Error, "#{command} failed with exit code #{status.exitstatus}: #{stderr}"
+        end
+
+        stdout.chomp
+      end
+
+      # Installs the dependencies specified in the `package.json` file
+      def install(frozen: false)
+        raise NotImplementedError
+      end
+
+      # Provides the "native" command for installing dependencies with this package manager for embedding into scripts
+      def native_install_command(frozen: false)
+        raise NotImplementedError
+      end
+
+      # Installs the dependencies specified in the `package.json` file
+      def install!(frozen: false)
+        raise_exited_with_non_zero_code_error unless install(frozen: frozen)
+      end
+
+      # Adds the given packages
+      def add(packages, type: :production)
+        raise NotImplementedError
+      end
+
+      # Adds the given packages
+      def add!(packages, type: :production)
+        raise_exited_with_non_zero_code_error unless add(packages, type: type)
+      end
+
+      # Removes the given packages
+      def remove(packages)
+        raise NotImplementedError
+      end
+
+      # Removes the given packages
+      def remove!(
+        packages
+      )
+        raise_exited_with_non_zero_code_error unless remove(packages)
+      end
+
+      # Runs the script assuming it is defined in the `package.json` file
+      def run(
+        script_name,
+        args = [],
+        silent: false
+      )
+        raise NotImplementedError
+      end
+
+      # Runs the script assuming it is defined in the `package.json` file
+      def run!(
+        script_name,
+        args = [],
+        silent: false
+      )
+        raise_exited_with_non_zero_code_error unless run(
+          script_name,
+          args,
+          silent: silent
+        )
+      end
+
+      # Provides the "native" command for running the script with args for embedding into shell scripts
+      def native_run_command(
+        script_name,
+        args = [],
+        silent: false
+      )
+        raise NotImplementedError
+      end
+
+      # Provides the "native" command for executing a package with args for embedding into shell scripts
+      def native_exec_command(
+        script_name,
+        args = []
+      )
+        raise NotImplementedError
+      end
+
+      private
+
+      def raise_exited_with_non_zero_code_error
+        raise Error, "#{binary} exited with non-zero code"
+      end
+
+      def build_full_cmd(sub_cmd, args)
+        [binary, sub_cmd, *args]
+      end
+
+      def raw(sub_cmd, args)
+        Kernel.system(*build_full_cmd(sub_cmd, args), chdir: @package_json.directory)
+      end
+    end
+  end
+end

data/lib/package_json/managers/bun_like.rb

@@ -0,0 +1,79 @@
+class PackageJson
+  module Managers
+    class BunLike < Base
+      def initialize(package_json)
+        super(package_json, binary_name: "bun")
+      end
+
+      # Installs the dependencies specified in the `package.json` file
+      def install(frozen: false)
+        raw("install", with_frozen_flag(frozen))
+      end
+
+      # Provides the "native" command for installing dependencies with this package manager for embedding into scripts
+      def native_install_command(frozen: false)
+        build_full_cmd("install", with_frozen_flag(frozen))
+      end
+
+      # Adds the given packages
+      def add(packages, type: :production)
+        raw("add", [package_type_install_flag(type)].compact + packages)
+      end
+
+      # Removes the given packages
+      def remove(packages)
+        raw("remove", packages)
+      end
+
+      # Runs the script assuming it is defined in the `package.json` file
+      def run(
+        script_name,
+        args = [],
+        silent: false
+      )
+        raw("run", build_run_args(script_name, args, _silent: silent))
+      end
+
+      # Provides the "native" command for running the script with args for embedding into shell scripts
+      def native_run_command(
+        script_name,
+        args = [],
+        silent: false
+      )
+        build_full_cmd("run", build_run_args(script_name, args, _silent: silent))
+      end
+
+      def native_exec_command(
+        script_name,
+        args = []
+      )
+        build_full_cmd("run", build_run_args(script_name, args, _silent: false))
+      end
+
+      private
+
+      def build_run_args(script_name, args, _silent:)
+        [script_name, *args]
+      end
+
+      def with_frozen_flag(frozen)
+        return ["--frozen-lockfile"] if frozen
+
+        []
+      end
+
+      def package_type_install_flag(type)
+        case type
+        when :production
+          nil
+        when :dev
+          "--dev"
+        when :optional
+          "--optional"
+        else
+          raise Error, "unsupported package install type \"#{type}\""
+        end
+      end
+    end
+  end
+end

data/lib/package_json/managers/npm_like.rb

@@ -0,0 +1,83 @@
+class PackageJson
+  module Managers
+    class NpmLike < Base
+      def initialize(package_json)
+        super(package_json, binary_name: "npm")
+      end
+
+      # Installs the dependencies specified in the `package.json` file
+      def install(frozen: false)
+        cmd = "install"
+        cmd = "ci" if frozen
+
+        raw(cmd, [])
+      end
+
+      # Provides the "native" command for installing dependencies with this package manager for embedding into scripts
+      def native_install_command(frozen: false)
+        cmd = "install"
+        cmd = "ci" if frozen
+
+        build_full_cmd(cmd, [])
+      end
+
+      # Adds the given packages
+      def add(packages, type: :production)
+        raw("install", [package_type_install_flag(type)] + packages)
+      end
+
+      # Removes the given packages
+      def remove(packages)
+        raw("remove", packages)
+      end
+
+      # Runs the script assuming it is defined in the `package.json` file
+      def run(
+        script_name,
+        args = [],
+        silent: false
+      )
+        raw("run", build_run_args(script_name, args, silent: silent))
+      end
+
+      # Provides the "native" command for running the script with args for embedding into shell scripts
+      def native_run_command(
+        script_name,
+        args = [],
+        silent: false
+      )
+        build_full_cmd("run", build_run_args(script_name, args, silent: silent))
+      end
+
+      def native_exec_command(
+        script_name,
+        args = []
+      )
+        build_full_cmd("exec", ["--no", "--offline"] + build_run_args(script_name, args, silent: false))
+      end
+
+      private
+
+      def build_run_args(script_name, args, silent:)
+        # npm assumes flags prefixed with - are for it, unless they come after a "--"
+        args = [script_name, "--", *args]
+
+        args.unshift("--silent") if silent
+        args
+      end
+
+      def package_type_install_flag(type)
+        case type
+        when :production
+          "--save-prod"
+        when :dev
+          "--save-dev"
+        when :optional
+          "--save-optional"
+        else
+          raise Error, "unsupported package install type \"#{type}\""
+        end
+      end
+    end
+  end
+end

data/lib/package_json/managers/pnpm_like.rb

@@ -0,0 +1,84 @@
+class PackageJson
+  module Managers
+    class PnpmLike < Base
+      def initialize(package_json)
+        super(package_json, binary_name: "pnpm")
+      end
+
+      # Installs the dependencies specified in the `package.json` file
+      def install(frozen: false)
+        raw("install", with_frozen_flag(frozen))
+      end
+
+      # Provides the "native" command for installing dependencies with this package manager for embedding into scripts
+      def native_install_command(frozen: false)
+        build_full_cmd("install", with_frozen_flag(frozen))
+      end
+
+      # Adds the given packages
+      def add(packages, type: :production)
+        raw("add", [package_type_install_flag(type)] + packages)
+      end
+
+      # Removes the given packages
+      def remove(packages)
+        raw("remove", packages)
+      end
+
+      # Runs the script assuming it is defined in the `package.json` file
+      def run(
+        script_name,
+        args = [],
+        silent: false
+      )
+        raw("run", build_run_args(script_name, args, silent: silent))
+      end
+
+      # Provides the "native" command for running the script with args for embedding into shell scripts
+      def native_run_command(
+        script_name,
+        args = [],
+        silent: false
+      )
+        build_full_cmd("run", build_run_args(script_name, args, silent: silent))
+      end
+
+      def native_exec_command(
+        script_name,
+        args = []
+      )
+        build_full_cmd("exec", build_run_args(script_name, args, silent: false))
+      end
+
+      private
+
+      def build_run_args(script_name, args, silent:)
+        args = [script_name, *args]
+
+        args.unshift("--silent") if silent
+        args
+      end
+
+      def with_frozen_flag(frozen)
+        return ["--frozen-lockfile"] if frozen
+
+        # we make frozen lockfile behaviour consistent with the other package managers
+        # as pnpm automatically enables frozen lockfile if it detects it's running in CI
+        ["--no-frozen-lockfile"]
+      end
+
+      def package_type_install_flag(type)
+        case type
+        when :production
+          "--save-prod"
+        when :dev
+          "--save-dev"
+        when :optional
+          "--save-optional"
+        else
+          raise Error, "unsupported package install type \"#{type}\""
+        end
+      end
+    end
+  end
+end