inquirex-tools 0.8.0 → 0.9.5

data/lib/inquirex/tools/version_bumper.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "colored2"
+require "open3"
+require "rubygems/version"
+require_relative "workspace"
+
+module Inquirex
+  module Tools
+    # Moves every lockstep package to one version, then proves each one still
+    # builds — the write half of the pair whose read half is {VersionChecker}.
+    #
+    # The family shares a serialization format, so a version that identifies
+    # one package identifies all of them. Bumping is therefore all-or-nothing:
+    # there is no supported way to move a single package.
+    #
+    # Writing a version and verifying it are one command on purpose. A version
+    # written but never checked is the failure this is meant to prevent: the
+    # number says the family agrees while one package no longer passes its own
+    # suite.
+    #
+    # @example Move the family to 0.9.2 and check every package
+    #   Inquirex::Tools::VersionBumper.new.call("0.9.2")   # => false if any check fails
+    class VersionBumper
+      # A version must be exactly MAJOR.MINOR.PATCH — no prereleases, because
+      # the npm packages and the gems would spell them differently.
+      SEMVER_RE = /\A\d+\.\d+\.\d+\z/
+
+      # Prefix for the refusal messages. This command's only feedback is what
+      # it prints, so the word carries weight.
+      ERROR = "ERROR"
+
+      # What each package is verified with. One recipe for gems and npm
+      # packages alike — every repo's justfile defines it, which is the point
+      # of having a justfile in each.
+      CHECK = %w[just check-all].freeze
+
+      # Rule across the report, sized to the rows.
+      RULE = ("—" * 52).freeze
+
+      # Bringing a checkout level with origin/main before its suite runs, so a
+      # bump is verified against what is actually on main rather than whatever
+      # the local clone last saw.
+      SYNC_STEPS = [
+        %w[fetch --tags origin],
+        %w[rebase origin/main]
+      ].freeze
+
+      # Runs one git command, capturing stdout *and* stderr.
+      #
+      # Capturing is the point. Left attached, a `git` run against a directory
+      # that is not a checkout writes "fatal: not a git repository" straight to
+      # the terminal — thirty such lines during the specs, which is noise the
+      # operator has to learn to ignore. The caller decides what is worth
+      # printing.
+      #
+      # @return [Array(Boolean, String)] success, and the combined output
+      DEFAULT_GIT = lambda { |dir, argv|
+        output, status = Open3.capture2e("git", "-C", dir, *argv)
+        [status.success?, output]
+      }
+
+      # Runs a package's own checks in its own directory.
+      DEFAULT_RUNNER = ->(dir, argv) { Dir.chdir(dir) { system(*argv) } }
+
+      # @param workspace [Workspace] the ecosystem checkout to rewrite
+      # @param out [IO] where report output goes
+      # @param git [#call] invoked with (dir, argv); returns [ok, output].
+      #   Injected so specs can assert what would run without touching a repo.
+      # @param runner [#call] invoked with (dir, argv) to run a package's
+      #   checks. Injected for the same reason: a unit test must not shell out
+      #   to six real suites.
+      def initialize(workspace: Workspace.new, out: $stdout, git: DEFAULT_GIT, runner: DEFAULT_RUNNER)
+        @workspace = workspace
+        @out = out
+        @git = git
+        @runner = runner
+      end
+
+      # Rewrites every lockstep package to the target version, then runs each
+      # package's own `just check-all`.
+      #
+      # Refuses to move backwards: a version already published cannot be
+      # reissued, so the target must be at least the highest current value.
+      #
+      # @param version [String] target, MAJOR.MINOR.PATCH
+      # @param verify [Boolean] run `just check-all` per package afterwards
+      # @return [Boolean] true when every package was written and checked
+      def call(version, verify: true)
+        return false unless valid?(version)
+
+        out.puts "Setting all lockstep packages to #{version} 🚨:"
+        each_package { |name, kind| write(name, kind, version) }
+        return true unless verify
+
+        out.puts
+        out.puts "Verifying each package with `#{CHECK.join(" ")}`:"
+        results = each_package { |name, _kind| check(name) }
+        report(results)
+      end
+
+      private
+
+      # @return [Workspace] the ecosystem checkout being rewritten
+      attr_reader :workspace
+
+      # @return [IO] where report output goes
+      attr_reader :out
+
+      # @return [#call] runs one git command, returning [ok, output]
+      attr_reader :git
+
+      # @return [#call] runs a package's checks, returning truthy on success
+      attr_reader :runner
+
+      # The one place the package list is walked, so adding a package changes
+      # nothing here.
+      #
+      # @yieldparam name [String] package name
+      # @yieldparam kind [Symbol] :gem or :npm
+      # @return [Hash{String => Object}] name => whatever the block returned
+      def each_package
+        Workspace::LOCKSTEP.to_h { |name, kind| [name, yield(name, kind)] }
+      end
+
+      # @return [void]
+      def write(name, kind, version)
+        workspace.write_version(name, version, kind)
+        row(name, kind.to_s.cyan, version.green)
+      end
+
+      # Runs one package's checks in its own directory.
+      #
+      # A package with no justfile is reported and skipped rather than failed:
+      # the fixture used by the specs has none, and a repo that has not grown
+      # one yet should not make a legitimate bump look broken.
+      #
+      # @param name [String] package name
+      # @return [Boolean, nil] pass/fail, or nil when skipped
+      def check(name)
+        dir = File.join(workspace.root, name)
+        unless File.exist?(File.join(dir, "justfile"))
+          row(name, "skip".yellow, "no justfile".yellow)
+          return nil
+        end
+
+        sync(name, dir)
+        passed = runner.call(dir, CHECK)
+        row(name, passed ? "ok".green : "FAIL".red, dir)
+        passed
+      end
+
+      # Brings one package level with origin/main before its suite runs.
+      #
+      # Two states are reported and left alone rather than acted on:
+      #
+      # - **not a git checkout** — nothing to sync, and running git here is what
+      #   printed "fatal: not a git repository" once per command per package.
+      # - **uncommitted changes** — the tree is *not* stashed. A version bump
+      #   that silently runs `git stash -u` can bury work the operator never
+      #   agreed to move, and the stash stack is shared across worktrees, so it
+      #   is not even reliably theirs to pop back. Rebasing on top of local
+      #   edits is equally unwelcome. Skipping is the only non-destructive
+      #   answer; the checks still run against what is on disk.
+      #
+      # @param name [String] package name
+      # @param dir [String] absolute path to the package
+      # @return [void]
+      def sync(name, dir)
+        state = workspace.git_state(name)
+        return row(name, "sync".yellow, "not a git checkout".yellow) if state[:clean].nil?
+        return row(name, "sync".yellow, "uncommitted changes — left alone".yellow) unless state[:clean]
+
+        SYNC_STEPS.each do |argv|
+          ok, output = git.call(dir, argv)
+          next if ok
+
+          row(name, "sync".red, "git #{argv.first} failed: #{output.to_s.lines.first&.strip}".red)
+          break
+        end
+      end
+
+      # The single formatting site for every line of the report.
+      #
+      # `format`, never `printf`: printf writes straight to $stdout and returns
+      # nil, so an injected out would receive one blank line per package while
+      # the real output went elsewhere.
+      #
+      # @return [void]
+      def row(name, state, detail)
+        out.puts format(" → %<name>-24s %<state>-6s %<detail>s", name: name.yellow, state:, detail:)
+      end
+
+      # @param results [Hash{String => Boolean, nil}] per-package check outcome
+      # @return [Boolean] true when nothing failed
+      def report(results)
+        failed = results.select { |_name, passed| passed == false }.keys
+        out.puts RULE
+        if failed.empty?
+          out.puts "OK: every package checked out".green
+          true
+        else
+          out.puts "#{ERROR.bold.red}: #{failed.join(", ")} failed `#{CHECK.join(" ")}`"
+          false
+        end
+      end
+
+      # Whether the target is well-formed and moves the family forward.
+      # Reports the reason it does not, since this is the CLI's only feedback.
+      #
+      # @param version [String] proposed target
+      # @return [Boolean]
+      def valid?(version)
+        unless SEMVER_RE.match?(version.to_s)
+          out.puts "#{ERROR.bold.red}: #{version.inspect} is not MAJOR.MINOR.PATCH"
+          return false
+        end
+
+        highest = workspace.versions.values.compact.max_by { Gem::Version.new(it) }
+        if highest && Gem::Version.new(highest) > Gem::Version.new(version)
+          out.puts "#{ERROR.bold.red}: #{version} is below the highest existing " \
+                   "version (#{highest}) — versions only go forward"
+          return false
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/inquirex/tools/version_checker.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "colored2"
+require_relative "workspace"
+
+module Inquirex
+  module Tools
+    # Reports version parity across the lockstep packages.
+    #
+    # Read-only by construction: nothing here writes a version file. Bumping is
+    # {VersionBumper}'s job. The split means a check can be run anywhere — CI, a
+    # dirty tree, a colleague's checkout — with no chance of editing something,
+    # and the two behaviours no longer share a flag that decides which happens.
+    #
+    # @example Check for drift
+    #   Inquirex::Tools::VersionChecker.new.call   # => false when versions differ
+    class VersionChecker
+      # @param workspace [Workspace] the ecosystem checkout to inspect
+      # @param out [IO] where report output goes
+      def initialize(workspace: Workspace.new, out: $stdout)
+        @workspace = workspace
+        @out = out
+      end
+
+      # Prints the current state of every lockstep package.
+      #
+      # @return [Boolean] true when all packages agree on one version
+      def call
+        versions = workspace.versions
+        print_table(versions)
+        verdict(versions)
+      end
+
+      # Parity plus git readiness: clean tree, on main, tagged at the version.
+      #
+      # @return [Boolean] true when every package could be published now
+      def preflight
+        ok = call
+        target = workspace.versions.values.compact.uniq.first
+        out.puts
+        out.puts "Release readiness:"
+
+        Workspace::LOCKSTEP.each_key do |name|
+          problems = readiness_problems(name, target)
+          # `.green`, not `.bright_green`: colored2 defines no such method, so
+          # the ready branch raised NoMethodError — and only the ready branch,
+          # which is why a preflight that found problems looked fine.
+          out.puts format("  %<name>-16s %<state>s", name: name, state: problems.empty? ? "ready".green : problems.join(", ").red)
+          ok &&= problems.empty?
+        end
+
+        out.puts
+        out.puts ok ? "ALL READY — publish with `gem push` / `npm publish`" : "NOT READY — resolve the above"
+        ok
+      end
+
+      private
+
+      # @return [Workspace] the ecosystem checkout being inspected
+      attr_reader :workspace
+
+      # @return [IO] where report output goes
+      attr_reader :out
+
+      # @param versions [Hash{String => String, nil}]
+      # @return [void]
+      def print_table(versions)
+        versions.each do |name, version|
+          # format, not printf: printf writes straight to $stdout and returns
+          # nil, so the injected out saw one blank line per package and the
+          # real table bypassed it entirely.
+          out.puts format(" → %<name>-30s %<kind>5s %<version>6s",
+            name:    name.to_s.yellow,
+            kind:    Workspace::LOCKSTEP[name].to_s.cyan,
+            version: (version || "MISSING").to_s.green)
+        end
+      end
+
+      # @param versions [Hash{String => String, nil}]
+      # @return [Boolean] true when every package agrees on one version
+      def verdict(versions)
+        out.puts "——————————————————————————————————"
+        distinct = versions.values.compact.uniq
+        if versions.value?(nil)
+          out.puts "DRIFT: a version could not be read (MISSING above)".red
+          false
+        elsif distinct.one?
+          out.puts "OK: all #{versions.size} at #{distinct.first}".green
+          true
+        else
+          out.puts "DRIFT: #{distinct.sort.join(", ")} — run `inquirex versions-bump <version>`".yellow
+          false
+        end
+      end
+
+      # Why a package is not publishable right now.
+      #
+      # @param name [String] package name
+      # @param target [String, nil] the version its tag must match
+      # @return [Array<String>] empty when ready
+      def readiness_problems(name, target)
+        state = workspace.git_state(name)
+        return ["no git checkout"] if state[:clean].nil?
+
+        problems = []
+        problems << "DIRTY" unless state[:clean]
+        problems << "on #{state[:branch]}" unless state[:branch] == "main"
+        problems << "untagged" unless state[:tags].any? { |tag| tag.delete_prefix("v") == target }
+        problems
+      end
+    end
+  end
+end

data/lib/inquirex/tools/workspace.rb

@@ -11,34 +11,34 @@ module Inquirex
     # walking up from the working directory looking for the sibling checkouts,
     # or taken from INQUIREX_ROOT.
     class Workspace
-      # Packages that must always carry the same version. They share one
-      # serialization format — the gem defines the DSL and emits step JSON,
-      # inquirex-js renders it, inquirex-webui prints it back to DSL,
-      # inquirex-llm extends the vocabulary, and inquirex-tools is the tooling
-      # that ships alongside them. A verb present in one and absent in another
-      # does not fail loudly; it drops data.
+      # Every package in the family, all carrying the same version. They share
+      # one serialization format — the gem defines the DSL and emits step JSON,
+      # inquirex-widget (npm; formerly @kigster/inquirex-js) renders it,
+      # inquirex-webui prints it back to DSL, inquirex-llm extends the
+      # vocabulary, inquirex-tty walks a flow in the terminal, and
+      # inquirex-tools is the tooling that ships alongside them. A verb present
+      # in one and absent in another does not fail loudly; it drops data.
       #
-      # `inquirex-tty` is deliberately absent: a developer tool outside the
-      # wire contract, versioned on its own cadence.
+      # Nothing is excluded. One version number across the whole family means
+      # "which combination has this bug?" is a lookup rather than an
+      # investigation.
       LOCKSTEP = {
-        "inquirex" => :gem,
-        "inquirex-llm" => :gem,
-        "inquirex-tools" => :gem,
-        "inquirex-js" => :npm,
-        "inquirex-webui" => :npm
+        "inquirex"        => :gem,
+        "inquirex-llm"    => :gem,
+        "inquirex-tools"  => :gem,
+        "inquirex-tty"    => :gem,
+        "inquirex-widget" => :npm,
+        "inquirex-webui"  => :npm
       }.freeze
 
-      # Excluded from lockstep, documented so the omission reads as deliberate.
-      EXCLUDED = %w[inquirex-tty].freeze
-
       # Repositories that carry a generated CHANGELOG.md but are not versioned
       # in lockstep.
-      CHANGELOG_ONLY = %w[inquirex-tty qualified-at].freeze
+      CHANGELOG_ONLY = %w[qualified-at].freeze
 
       GEM_VERSION_RE = /VERSION\s*=\s*"([^"]+)"/
 
       # Directories whose presence identifies the ecosystem root.
-      MARKERS = %w[inquirex inquirex-js].freeze
+      MARKERS = %w[inquirex inquirex-widget].freeze
 
       # @return [String] absolute path to the ecosystem root
       attr_reader :root
@@ -92,18 +92,21 @@ module Inquirex
       #
       # @param name [String] package name
       # @param version [String] new version
+      # @param kind [Symbol] :gem or :npm — which version line to rewrite.
+      #   Passed by the caller rather than looked up here so a caller that
+      #   already knows the kind does not pay for a second lookup.
       # @return [void]
-      def write_version(name, version)
+      def write_version(name, version, kind)
         file = version_file(name)
         raise Error, "no version file for #{name}" unless file
 
         src = File.read(file)
-        updated =
-          if LOCKSTEP[name] == :gem
-            src.sub(GEM_VERSION_RE, %(VERSION = "#{version}"))
-          else
-            src.sub(/"version":\s*"[^"]*"/, %("version": "#{version}"))
-          end
+        updated = case kind
+                  when :gem
+                    src.sub(GEM_VERSION_RE, %(VERSION = "#{version}"))
+                  when :npm
+                    src.sub(/"version":\s*"[^"]*"/, %("version": "#{version}"))
+                  end
         File.write(file, updated)
       end
 
@@ -114,9 +117,9 @@ module Inquirex
         return { clean: nil, branch: nil, tags: [] } unless File.exist?(File.join(dir, ".git"))
 
         {
-          clean: `git -C #{dir} status --porcelain 2>/dev/null`.strip.empty?,
+          clean:  `git -C #{dir} status --porcelain 2>/dev/null`.strip.empty?,
           branch: `git -C #{dir} rev-parse --abbrev-ref HEAD 2>/dev/null`.strip,
-          tags: `git -C #{dir} tag --points-at HEAD 2>/dev/null`.split("\n").map(&:strip).reject(&:empty?)
+          tags:   `git -C #{dir} tag --points-at HEAD 2>/dev/null`.split("\n").map(&:strip).reject(&:empty?)
         }
       end
 

data/lib/inquirex/tools.rb

@@ -2,7 +2,10 @@
 
 require_relative "tools/version"
 require_relative "tools/workspace"
-require_relative "tools/versions"
+require_relative "tools/version_checker"
+require_relative "tools/version_bumper"
+require_relative "tools/publisher"
+require_relative "tools/releaser"
 require_relative "tools/changelogs"
 
 module Inquirex
@@ -17,13 +20,17 @@ module Inquirex
   # required to have zero runtime dependencies, and nothing added here changes
   # that, because nothing here is loaded by the runtime gems.
   #
-  # Executables:
+  # It ships one executable, `inquirex`, with these subcommands:
   #
-  # - `inquirex-version`    — version parity across the lockstep packages
-  # - `inquirex-changelogs` — regenerate CHANGELOG.md from merged PRs
+  # - `versions-check` — version parity across the lockstep packages
+  # - `versions-bump`  — move every lockstep package to one version
+  # - `publish`        — publish every package to RubyGems and npm
+  # - `create-release` — tag and create a GitHub release for every package
+  # - `changelogs`     — regenerate CHANGELOG.md from merged PRs
+  # - `version`        — this gem's own version
   #
   # @example Check whether the family is releasable
-  #   Inquirex::Tools::Versions.new.preflight  # => true when every package is ready
+  #   Inquirex::Tools::VersionChecker.new.preflight  # => true when every package is ready
   module Tools
     class Error < StandardError; end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-tools
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.5
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: colored2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Ships the `inquirex` command: lockstep version management across the
   Inquirex gems and npm packages, changelog regeneration, and release
@@ -32,24 +46,42 @@ email:
 - kigster@gmail.com
 executables:
 - inquirex
+- inquirexor
 extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".env.encrypted"
+- ".env.example"
+- ".envrc"
 - ".github_changelog_generator"
+- ".relaxed_rubocop.yml"
+- ".sops.yaml"
+- ".sopsy.sha"
+- ".sopsy.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/badges/coverage_badge.svg
+- docs/monorepo-migration.md
 - exe/inquirex
+- exe/inquirexor
+- justfile
 - lib/inquirex/tools.rb
 - lib/inquirex/tools/changelogs.rb
 - lib/inquirex/tools/commands.rb
 - lib/inquirex/tools/commands/changelogs.rb
+- lib/inquirex/tools/commands/create_release.rb
+- lib/inquirex/tools/commands/publish.rb
 - lib/inquirex/tools/commands/version.rb
-- lib/inquirex/tools/commands/versions.rb
+- lib/inquirex/tools/commands/versions_bump.rb
+- lib/inquirex/tools/commands/versions_check.rb
+- lib/inquirex/tools/publisher.rb
+- lib/inquirex/tools/releaser.rb
 - lib/inquirex/tools/version.rb
-- lib/inquirex/tools/versions.rb
+- lib/inquirex/tools/version_bumper.rb
+- lib/inquirex/tools/version_checker.rb
 - lib/inquirex/tools/workspace.rb
 - sig/inquirex/tools.rbs
 homepage: https://github.com/kigster/inquirex-tools

data/lib/inquirex/tools/commands/versions.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module Inquirex
-  module Tools
-    module Commands
-      # Reports and enforces version parity across the lockstep packages.
-      #
-      # Plural on purpose: `inquirex version` prints this tool's own version,
-      # `inquirex versions` manages the family's.
-      class Versions < Dry::CLI::Command
-        desc "Check, set, or preflight the family's lockstep version"
-
-        option :set, type: :string, desc: "Move every lockstep package to this version"
-        option :preflight, type: :boolean, default: false,
-                           desc: "Also check clean trees, main branch, and tags"
-
-        example [
-          "                      # report parity, exit 1 on drift",
-          "--set 0.8.0           # move all five packages",
-          "--preflight           # release readiness"
-        ]
-
-        # @param set [String, nil] target version
-        # @param preflight [Boolean]
-        # @return [void]
-        def call(set: nil, preflight: false, **)
-          versions = Inquirex::Tools::Versions.new
-          ok =
-            if set then versions.set(set)
-            elsif preflight then versions.preflight
-            else versions.check
-            end
-          exit(1) unless ok
-        rescue Inquirex::Tools::Error => e
-          warn "ERROR: #{e.message}"
-          exit 1
-        end
-      end
-    end
-  end
-end