featureparity 0.0.27 → 0.0.29

data/lib/fp/commands/coverage.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # fp coverage [--project X] [--surface api] [--all] [--json]
+    #
+    # Draft coverage: which draft requirements have marked tests or evidence on which
+    # surfaces, and which have none.
+    #
+    # The gate measures active requirements only (plus ones an open proposal demoted), so
+    # on a freshly onboarded project — where every requirement is still a draft — `fp
+    # check` says "Nothing to enforce yet" and `fp list --gaps` says "No gaps found". The
+    # agent that just proposed the catalog and marked the tests had no way to confirm its
+    # work, and nothing to hand the human but "trust me" (Fizzy #1786). This reads the
+    # parity report's `drafts` section, where the server resolves each draft's cells from
+    # evidence exactly as it would once the draft is active.
+    #
+    # It ends with a plain list of drafts that have no evidence on a required surface —
+    # the "requirements with no test" section an onboarding agent hands the human.
+    #
+    # Informational only. Drafts are reported, never gated; this command always exits 0
+    # on a successful read.
+    class Coverage < Base
+      help_summary 'Show which draft requirements have evidence on which surfaces (never gated)'
+      help_usage 'fp coverage [--project <slug>] [--surface X] [--all]'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, 'Limit to one surface'
+      help_flag :all, 'Also list the measured requirements (active, or under review) the gate checks'
+      help_example 'fp coverage', 'Drafts × surfaces, then the drafts with no evidence'
+      help_example 'fp coverage --all --json'
+      help_note "Drafts are not enforced: a human activates a draft before fp check gates on it.\n" \
+                'A cell reads the same here as it will in the matrix once the draft is active.'
+
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        all: :boolean
+      }.freeze
+
+      def run(args)
+        opts, = parse_flags(args, KNOWN_FLAGS)
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+        project_id = resolve_project_id(project_slug)
+        surface = opts[:surface] || project_config.surface
+
+        result = client.get_parity_with_drafts(project_id, surface: surface)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        report = result[:data]['parity'] || {}
+        unless report.key?('drafts')
+          output.error('This FeatureParity API does not report draft coverage yet (it predates ' \
+                       '`include_drafts`). Nothing was checked.')
+          exit 1
+        end
+
+        render(report, project_slug, surface, all: opts[:all])
+      end
+
+      # Drafts with no evidence on at least one required surface, as
+      # [{ 'slug', 'title', 'surfaces' => [...] }]. "No evidence" is the `missing` state:
+      # nothing — not even a stub or a red test — is filed for that surface.
+      def self.untested(drafts)
+        Array(drafts).filter_map do |row|
+          bare = Array(row['cells']).select { |c| c['state'] == 'missing' }.map { |c| c['surface'] }
+          next if bare.empty?
+
+          { 'slug' => row['slug'], 'title' => row['title'], 'surfaces' => bare }
+        end
+      end
+
+      # The drafts × surfaces table plus the "no evidence" list, for text output. Shared
+      # with `fp check --include-drafts`, so the two can't describe drafts differently.
+      def self.print_drafts(output, rows, surfaces, show_status: false)
+        if rows.empty?
+          puts 'No draft requirements.'
+          return
+        end
+
+        headers = %w[SLUG]
+        headers << 'STATUS' if show_status
+        headers += surfaces
+        table = rows.map do |row|
+          by_surface = Array(row['cells']).to_h { |c| [c['surface'], c['state']] }
+          cells = surfaces.map { |key| by_surface.key?(key) ? Parity.glyph(by_surface[key]) : Parity::NOT_REQUIRED }
+          line = [row['slug']]
+          line << row['status'] if show_status
+          line + cells
+        end
+        output.table(headers, table)
+        puts Parity::LEGEND
+      end
+
+      def self.print_untested(untested)
+        puts
+        if untested.empty?
+          puts 'Every draft has evidence on each of its required surfaces.'
+          return
+        end
+
+        puts "#{untested.size} draft(s) with no evidence on a required surface:"
+        untested.each { |u| puts "  #{u['slug']} — no evidence on: #{u['surfaces'].join(', ')}" }
+      end
+
+      private
+
+      def render(report, project_slug, surface, all:)
+        drafts = report['drafts'] || []
+        surfaces = report['surfaces'] || []
+        untested = self.class.untested(drafts)
+
+        payload = {
+          'project' => project_slug,
+          'surface' => surface,
+          'surfaces' => surfaces,
+          'drafts' => drafts,
+          'untested' => untested
+        }
+        payload['measured'] = report['requirements'] || [] if all
+
+        output.success(payload) do
+          scope = surface ? " (surface: #{surface})" : ''
+          puts "Draft coverage: #{project_slug}#{scope}"
+          puts
+
+          if all
+            measured = report['requirements'] || []
+            puts "Measured by the gate (#{measured.size}):"
+            if measured.empty?
+              puts 'None — no requirement is active yet.'
+            else
+              self.class.print_drafts(output, measured, surfaces, show_status: true)
+            end
+            puts
+            puts "Drafts (#{drafts.size}):"
+          end
+
+          self.class.print_drafts(output, drafts, surfaces)
+          self.class.print_untested(untested) unless drafts.empty?
+          puts
+          puts 'Drafts are reported, never gated. A human activates a draft before fp check enforces it.'
+        end
+      end
+    end
+  end
+end

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,9 @@ 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
             projects create <slug> --name ... Create a project (owned by your key's owner)
@@ -57,11 +60,17 @@ 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
             analyze [<slug>] --project <slug> Triage requirement quality (read-only; never proposes)
             changes [--source-url URL] [--github-pr]  Show or publish work-item-linked activity
@@ -71,12 +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
@@ -159,6 +172,30 @@ module Fp
             A stale or later candidate needs a new assessment. A PR candidate becomes accepted only
             when a default-branch CI report later observes the same fingerprint.
 
+          SPOT CHECKS
+            A green receipt says a marked test ran and passed, not that it checks what the
+            requirement promises. `fp spot-check` picks an active requirement with evidence at
+            random, prints its acceptance beside the source of every locally marked test, and
+            gives the agent running it a brief: match each clause to an assertion, then break
+            the product code and confirm a test fails. Run it on a schedule or by hand.
+
+              fp spot-check                     # a random pick; prints the seed to repeat it
+              fp spot-check --count 5 --surface cli --json
+              fp spot-check print_container_qr print_label   # chosen requirements
+              fp spot-check --all               # every active requirement with evidence
+              fp spot-check --test test/qr_test.rb:42        # the test there, and its requirement
+              fp spot-check --count 3 --prompt | claude -p   # hand it straight to an agent
+              fp spot-check --jev               # add Jev's first read (paid plans)
+
+            `--prompt` prints the spot check as instructions for an agent, with what to report
+            back. `--jev` asks Jev, before the agent starts, whether each requirement's tests
+            appear to cover its acceptance, and which gap is likeliest. It's a hint for aiming
+            the probe, not a verdict. Jev is for paid plans: without one the spot check runs
+            without it.
+
+            It records nothing and never edits a test or a requirement. A test that stays
+            green when the promise is broken goes to a human.
+
           AUTHENTICATION
             Set FP_API_KEY environment variable, or use a profile:
 
@@ -422,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

@@ -31,7 +31,11 @@ module Fp
         'removal_proposed' => 'deletion proposed',
         'change_approved' => 'change approved',
         'change_rejected' => 'change rejected',
-        'decision_recorded' => 'decision recorded'
+        'decision_recorded' => 'decision recorded',
+        'question_asked' => 'question asked',
+        'question_resolved' => 'question resolved',
+        'change_commented' => 'commented on the proposal',
+        'commented' => 'commented'
       }.freeze
 
       # A member's own stance on a requirement that already has a status (Fizzy #1478),
@@ -110,6 +114,9 @@ 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'])
         print_evidence_diff(change['evidence_diff'])
@@ -117,6 +124,14 @@ module Fp
         puts
       end
 
+      # The team's comments (Fizzy #1494) and comments on a proposal, so an agent reading
+      # the history sees the discussion, not just that one happened.
+      def print_comment(change)
+        change['body'].to_s.each_line { |line| puts "  > #{line.chomp}" } if present?(change['body'])
+        mentions = Array(change['mentions'])
+        puts "  tagged: #{mentions.join(', ')}" unless mentions.empty?
+      end
+
       def print_source(source)
         return if source.nil? || source.empty?