featureparity 0.0.28 → 0.0.30

data/lib/fp/commands/doctor.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require 'rbconfig'
+
+module Fp
+  module Commands
+    # fp doctor [--dir PATH] [--json]
+    #
+    # Says whether fp will work here, and what this repo needs before its tests can report
+    # (Fizzy #1786). Purely local: no API calls, no key needed.
+    #
+    #   Ruby     which Ruby is running fp, where the gem lives, and whether this directory
+    #            pins a different Ruby (.ruby-version, .tool-versions, mise.toml). A
+    #            version-manager shim resolves `fp` against the *pinned* Ruby, so a gem
+    #            installed under another one fails inside the repo with
+    #            `mise ERROR No version is set for shim: fp` and works from /tmp.
+    #   Config   the API environment (warning off production), whether a key resolved,
+    #            and which .featureparity.yml applies.
+    #   Repo     RepoDetector's summary: test runners and the command that makes each emit
+    #            a report, suggested surfaces, database and devcontainer.
+    #
+    # The shim error itself happens before fp starts, so doctor can only catch it when fp
+    # is reached some other way (another Ruby's bin dir, from /tmp). The skill and the
+    # generated AGENTS.md section describe that case for the agent that hits it.
+    class Doctor < Base
+      help_summary 'Check that fp works here: Ruby and version-manager pins, config, and what the repo needs'
+      help_usage 'fp doctor [--dir PATH]'
+      help_flag :dir, 'Directory to check (defaults to the working directory)'
+      help_example 'fp doctor'
+      help_example 'fp doctor --json', 'Machine-readable, for an agent to act on'
+      help_note "Purely local; makes no API calls, so it works without a key.\n" \
+                "If `fp` itself fails with `mise ERROR No version is set for shim: fp`, the shim stopped it\n" \
+                'before fp could run: install the gem under the pinned Ruby (`gem install featureparity` in the repo).'
+
+      KNOWN_FLAGS = { dir: :string }.freeze
+
+      # Nearest file wins, and within one directory mise's own precedence applies.
+      PIN_FILES = %w[mise.toml .mise.toml .tool-versions .ruby-version].freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        dir = File.expand_path(opts[:dir] || Dir.pwd)
+        unless File.directory?(dir)
+          output.error("Not a directory: #{dir}")
+          exit 1
+        end
+
+        report = {
+          ruby: ruby_report(dir),
+          config: config_report(dir),
+          repo: RepoDetector.new(repo_root(dir)).detect
+        }
+        report[:agents_section] = agents_section_report(repo_root(dir))
+
+        output.success(report) { print_report(report) }
+      end
+
+      # The nearest Ruby pin at or above dir: { version:, file:, manager: } or nil.
+      def self.ruby_pin(dir)
+        current = File.expand_path(dir)
+        loop do
+          PIN_FILES.each do |name|
+            file = File.join(current, name)
+            next unless File.file?(file)
+
+            version = parse_pin(file)
+            return { version: version, file: file, manager: manager_for(name) } if version
+          end
+          parent = File.dirname(current)
+          return nil if parent == current
+
+          current = parent
+        end
+      end
+
+      def self.parse_pin(file)
+        text = File.read(file)
+        raw = case File.basename(file)
+              when '.ruby-version' then text.lines.first.to_s.strip
+              when '.tool-versions' then text[/^\s*ruby\s+(\S+)/, 1]
+              else text[/^\s*ruby\s*=\s*(?:\[\s*)?(?:\{[^}]*?version\s*=\s*)?["']([^"']+)["']/, 1]
+              end
+        raw = raw.to_s.sub(/\Aruby-/, '').strip
+        raw.empty? ? nil : raw
+      rescue SystemCallError
+        nil
+      end
+
+      def self.manager_for(name)
+        case name
+        when 'mise.toml', '.mise.toml' then 'mise'
+        when '.tool-versions' then 'mise or asdf'
+        else 'mise, rbenv, chruby or asdf'
+        end
+      end
+
+      # "3.4" pins any 3.4.x; "latest"/"system" pin nothing we can check.
+      def self.version_matches?(pinned, running)
+        return true unless pinned.match?(/\A\d+(\.\d+)*\z/)
+
+        running.split('.').first(pinned.split('.').length) == pinned.split('.')
+      end
+
+      private
+
+      def repo_root(dir)
+        found = ProjectConfig.find_file(dir)
+        found ? File.dirname(found) : dir
+      end
+
+      def ruby_report(dir)
+        running = RUBY_VERSION
+        pin = self.class.ruby_pin(dir)
+        mismatch = pin && !self.class.version_matches?(pin[:version], running)
+        fp_on_path = which('fp')
+
+        {
+          version: running,
+          ruby: RbConfig.ruby,
+          fp_version: Fp::VERSION,
+          gem_path: gem_path,
+          gem_bindir: Gem.bindir,
+          fp_on_path: fp_on_path,
+          fp_on_path_is_shim: fp_on_path&.include?('/shims/') || false,
+          pinned: pin && pin[:version],
+          pinned_by: pin && pin[:file],
+          mismatch: !!mismatch,
+          fixes: mismatch ? shim_fixes(pin, running) : []
+        }
+      end
+
+      def shim_fixes(pin, running)
+        version = pin[:version]
+        fixes = []
+        fixes << if pin[:manager] == 'mise' || which('mise')
+                   "mise exec ruby@#{version} -- gem install featureparity"
+                 elsif which('rbenv')
+                   'gem install featureparity && rbenv rehash   # run inside this directory'
+                 elsif which('asdf')
+                   'gem install featureparity && asdf reshim ruby   # run inside this directory'
+                 else
+                   "gem install featureparity   # run inside this directory, under Ruby #{version}"
+                 end
+        fixes << "export PATH=\"#{Gem.bindir}:$PATH\"   # or keep using fp from Ruby #{running}"
+        fixes
+      end
+
+      def gem_path
+        spec = Gem.loaded_specs['featureparity']
+        spec ? spec.full_gem_path : File.expand_path('../../..', __dir__)
+      end
+
+      def which(name)
+        ENV['PATH'].to_s.split(File::PATH_SEPARATOR).each do |entry|
+          candidate = File.join(entry, name)
+          return candidate if File.file?(candidate) && File.executable?(candidate)
+        end
+        nil
+      end
+
+      def config_report(dir)
+        r = config.resolved
+        project = ProjectConfig.discover(dir)
+        {
+          environment: r[:environment],
+          api_url: r[:api_url],
+          profile: r[:profile],
+          production: r[:environment] == 'production',
+          api_key_present: r[:api_key_present],
+          api_key_source: r[:api_key_source],
+          project_config: project.path,
+          project: project.project
+        }
+      end
+
+      # Which fp wrote this repo's AGENTS.md section, so a stale one is visible.
+      def agents_section_report(root)
+        Init::AGENT_DOC_CANDIDATES.filter_map do |name|
+          file = File.join(root, name)
+          next unless File.file?(file)
+
+          content = File.read(file)
+          next unless content.include?(Init::AGENTS_MARKER)
+
+          written = content[Init::AGENTS_VERSION_RE, 1]
+          { path: name, written_by: written, current: written == Fp::VERSION }
+        end
+      end
+
+      def print_report(report)
+        ruby = report[:ruby]
+        cfg = report[:config]
+        repo = report[:repo]
+
+        puts "fp #{ruby[:fp_version]} on Ruby #{ruby[:version]} (#{ruby[:ruby]})"
+        puts "  Gem:          #{ruby[:gem_path]}"
+        puts "  fp on PATH:   #{ruby[:fp_on_path] || '(not found)'}#{ruby[:fp_on_path_is_shim] ? '  [version-manager shim]' : ''}"
+        if ruby[:pinned]
+          state = ruby[:mismatch] ? '⚠ differs from the Ruby running fp' : 'matches'
+          puts "  Ruby pin:     #{ruby[:pinned]} (#{ruby[:pinned_by]}) — #{state}"
+        end
+        if ruby[:mismatch]
+          puts
+          puts "  This directory pins Ruby #{ruby[:pinned]}, but fp is installed under #{ruby[:version]}."
+          puts '  A version-manager shim runs `fp` with the pinned Ruby, where the gem is missing, and'
+          puts '  fails before fp starts (`mise ERROR No version is set for shim: fp`). Fix one of:'
+          ruby[:fixes].each { |fix| puts "    #{fix}" }
+        end
+
+        puts
+        puts 'Config'
+        env = cfg[:environment] || '(unknown)'
+        puts "  Environment:  #{env} (#{cfg[:api_url]})#{cfg[:profile] ? "  [profile #{cfg[:profile]}]" : ''}"
+        puts "  ⚠ Not production: writes go to '#{env}'. Run `fp whoami` to see why." unless cfg[:production]
+        puts "  API key:      #{cfg[:api_key_present] ? "present [from #{cfg[:api_key_source]}]" : 'not set (export FP_API_KEY=fp_... or fp setup)'}"
+        puts "  Project file: #{cfg[:project_config] ? "#{cfg[:project_config]} (project: #{cfg[:project] || '?'})" : 'none — run `fp init --detect`, then `fp init --project <slug>`'}"
+        report[:agents_section].each do |section|
+          stamp = section[:written_by] ? "fp #{section[:written_by]}" : 'an fp that predates version stamps'
+          note = section[:current] ? '' : ' — `fp init --force` refreshes it'
+          puts "  #{section[:path]}:    FeatureParity section written by #{stamp}#{note}"
+        end
+
+        puts
+        RepoDetector.print_summary(repo)
+      end
+    end
+  end
+end

data/lib/fp/commands/help.rb

@@ -39,6 +39,8 @@ module Fp
 
           COMMANDS
             init --project <slug>             Onboard this repo: config, CI gate, agent docs
+            init --detect                     Suggest a slug, surfaces and test commands (writes nothing)
+            doctor                            Check Ruby/version-manager pins, config, and what the repo needs
             tutorial                          Write Hexhaven, a sample repo to practise on
             projects                          List projects you have access to
             projects show <slug>              View a project and its surfaces
@@ -58,11 +60,15 @@ module Fp
             list --project <slug>             List active requirements
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
+            propose --file reqs.yml           Propose a batch of drafts, validated all-or-nothing
+            propose ... --dry-run             Validate and lint the wording; write nothing
             propose-change <slug> ...         Propose a change to an existing requirement
             propose-change <slug> --removal   Propose deleting a requirement
             propose-change <slug> --no-parent Propose un-nesting a child to top level
             propose-change <slug> --withdraw  Withdraw your own open proposal (to amend it)
             comment <slug> --body "..."       Comment on a requirement's open change proposal
+            question <slug> "<question>"      Attach an open question for a human to a draft
+            questions <slug> [--open]         List a requirement's questions and their answers
             comments <slug>                   Read the team's comments on a requirement
             comments <slug> --body "..." [--tag who,...]  Comment on a requirement, tagging people or agents
             history <slug> --project <slug>   Show a requirement's change history + diffs
@@ -74,13 +80,16 @@ module Fp
             attach rm <slug> <id>             Delete an attachment
             conversation <id>                 Read a Pari conversation for agent review
             report <slug> --project <slug>... Report evidence for a requirement
-            report --junit <file> ...         Upload evidence from a JUnit XML report (no CI)
+            mark <slug> <file>:<line>         Insert an fp:<slug> marker above a test (file's comment syntax)
+            report --junit <file> ...         Upload evidence from a JUnit XML or RSpec JSON report (no CI)
+            run [report flags] -- <cmd...>    Run rspec/pytest/vitest/playwright with a formatter added, then report
             ci-report --junit <file> ...      Ingest CI test results (passing/failing) — CI only
             ci-report --junit <file> --pr URL Ingest a PR's CI results as pr_passing — CI only
             changed-tests                     List unresolved bound-test revision findings
             changed-tests assess <id> ...     Explain whether an exact revision still proves its requirement
             spot-check [<slug>...]            Check requirements' tests prove them (random, --count, --all, --test)
             check                             Enforce parity; exits non-zero on violations
+            coverage [--all]                  Show which drafts have evidence on which surfaces (never gated)
             matrix --project <slug>           Show the parity matrix
             export --project <slug>           Export all requirements as a Markdown document
             profile add|list                  Manage named profiles
@@ -450,6 +459,9 @@ module Fp
             # fp parses the report, finds the fp:<slug> markers in the test files,
             # and reports evidence for every requirement the suite covered.
             #   rspec --format RspecJunitFormatter --out junit.xml   # (or your runner's equivalent)
+            # RSpec's own `--format json --out rspec.json` works as --junit too, with no extra gem.
+            # Or let fp add the formatter and report in one step (rspec, pytest, vitest, playwright):
+            #   fp run --surface api --repo stowzilla/marketplace -- bundle exec rspec
             fp report --junit junit.xml --project stowzilla \\
               --surface api \\
               --repo stowzilla/marketplace \\

data/lib/fp/commands/history.rb

@@ -32,6 +32,8 @@ module Fp
         'change_approved' => 'change approved',
         'change_rejected' => 'change rejected',
         'decision_recorded' => 'decision recorded',
+        'question_asked' => 'question asked',
+        'question_resolved' => 'question resolved',
         'change_commented' => 'commented on the proposal',
         'commented' => 'commented'
       }.freeze
@@ -112,6 +114,8 @@ module Fp
         puts "* #{label} — #{actor} (#{kind}) at #{format_time(change['recorded_at'])}"
         puts "  #{change['reason']}" if present?(change['reason'])
         puts "  note: #{change['note']}" if change['type'] == 'decision_recorded' && present?(change['note'])
+        puts "  question: #{change['text']}" if present?(change['text'])
+        puts "  #{change['resolution'] || 'answered'}: #{change['answer']}" if present?(change['answer'])
         print_comment(change) if %w[commented change_commented].include?(change['type'])
         print_source(change['source'])
         print_diff(change['changes'])