featureparity 0.0.27 → 0.0.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b09491a1b44b4ba693dfd567cdec5068d3410c577066435b541b2e9520ae04f
-  data.tar.gz: c9b7fb84bee3dbb3e8dfd8ee29f7c4d878747c0157efaa63fb020ead7934b2e7
+  metadata.gz: 5cef61c9093573a494f9d27b203554e51dfc2f0a6d60ae43e666564c8e2b1740
+  data.tar.gz: 7162500244354be8c93a78499e479ac30a7df2d25ab4f818ce3451a6819ce960
 SHA512:
-  metadata.gz: cdf6cc31e230d20555285da1b44ee1816e94a88d3a5e3c02b22569cc63034d2f038d5183c12191f9ba446e5fdbc78a44ebe0b485e476f0dd5b9e021675338500
-  data.tar.gz: c9b9337383f9e7aecfa8caec130d99e3a1e93452481d14ffe1e0f95bd63c495480241d3b1578f0ff01ca5c7f81cc3b969a78cf232947a563cd307ade34b255c1
+  metadata.gz: a4733078f1af140723dadb54a0ed5e3ba5c80b771a48ba9f8364c6dcfb088cb9e3c39c79fac27b0fd5083e2339e47b8b6fb76fe5c54fde772f68fdbc2a005e7d
+  data.tar.gz: 21330096e2f61cf6100dc54708c25818647f88581e0d0ef073bc84b2ec532556582012d899a663a0e96ce9e757ff6f5ae0ec51338be797bc19363f40e97d86af

data/lib/fp/cli.rb

@@ -7,6 +7,9 @@ module Fp
   class CLI
     COMMANDS = {
       'init' => Commands::Init,
+      'tutorial' => Commands::Tutorial,
+      'doctor' => Commands::Doctor,
+      'run' => Commands::Run,
       'projects' => Commands::Projects,
       'surfaces' => Commands::Surfaces,
       'showroom' => Commands::Showroom,
@@ -14,14 +17,20 @@ module Fp
       'show' => Commands::Show,
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
+      'mark' => Commands::Mark,
       'comment' => Commands::Comment,
+      'question' => Commands::Question,
+      'questions' => Commands::Questions,
+      'comments' => Commands::Comments,
       'history' => Commands::History,
       'analyze' => Commands::Analyze,
       'changes' => Commands::Changes,
       'report' => Commands::Report,
       'ci-report' => Commands::CiReport,
       'changed-tests' => Commands::ChangedTests,
+      'spot-check' => Commands::SpotCheck,
       'check' => Commands::Check,
+      'coverage' => Commands::Coverage,
       'matrix' => Commands::Matrix,
       'export' => Commands::Export,
       'profile' => Commands::Profile,
@@ -39,6 +48,9 @@ module Fp
     class << self
       def run(argv)
         args = argv.dup
+        # Everything after `--` belongs to another program (`fp run -- pytest -p no:cov`),
+        # so global flags and --help are only looked for before it.
+        passthrough = (split = args.index('--')) ? args.slice!(split..) : []
         global_opts = extract_global_options(args)
 
         command_name = args.shift || 'help'
@@ -68,7 +80,7 @@ module Fp
 
         # Profile/config commands don't need auth. `init` is here too: it only writes
         # files into the repo, and onboarding a repo must work before anyone has a key.
-        needs_auth = !%w[init profile config repos setup whoami version help].include?(command_name)
+        needs_auth = !%w[init doctor profile config repos setup whoami version help mark].include?(command_name)
 
         if needs_auth
           config = Config.new(profile: global_opts[:profile], api_url: global_opts[:api_url])
@@ -84,7 +96,7 @@ module Fp
 
         output = Output.new(json: global_opts[:json])
         command = command_class.new(client: client, output: output, config: config)
-        command.run(args)
+        command.run(args + passthrough)
       rescue Interrupt
         warn "\nAborted."
         exit 130

data/lib/fp/client.rb

@@ -208,6 +208,12 @@ module Fp
       post("/api/requirements/#{requirement_id}/analyze", body)
     end
 
+    # POST /requirements/:id/test_review — Jev's read of whether these tests check what
+    # the requirement promises (`fp spot-check --jev`). Paid plans only (402 otherwise).
+    def review_spot_check_tests(requirement_id, tests)
+      post("/api/requirements/#{requirement_id}/test_review", { tests: tests })
+    end
+
     # GET /requirements/:id/changes
     #
     # A requirement's change history: what it was, what changed, who changed it, and
@@ -241,6 +247,37 @@ module Fp
       post("/api/requirements/#{requirement_id}/changes/#{change_id}/comment", params)
     end
 
+    # GET /requirements/:id/questions
+    #
+    # The questions left for a human on a requirement (Fizzy #1786), open and resolved.
+    def list_requirement_questions(requirement_id)
+      get("/api/requirements/#{requirement_id}/questions")
+    end
+
+    # POST /requirements/:id/questions
+    #
+    # Attach an open question for a human to a draft (or active) requirement. There is
+    # no resolve method: only a human answers or dismisses, from the web app.
+    def ask_requirement_question(requirement_id, text)
+      post("/api/requirements/#{requirement_id}/questions", { text: text })
+    end
+
+    # GET /requirements/:id/comments
+    #
+    # The team's comments on a requirement, oldest first, plus who can be tagged:
+    # `mentionable` (people) and `mentionable_agents` (Fizzy #1494).
+    def list_requirement_comments(requirement_id)
+      get("/api/requirements/#{requirement_id}/comments")
+    end
+
+    # POST /requirements/:id/comments
+    #
+    # Comment on a requirement. `mentions` are emails, `agent_mentions` agent key ids;
+    # tagged people are emailed and tagged agents fire the project's webhooks.
+    def comment_on_requirement(requirement_id, params)
+      post("/api/requirements/#{requirement_id}/comments", params)
+    end
+
     # DELETE /requirements/:id/changes/:change_id
     #
     # Withdraw an open proposal. Only the proposal's author can withdraw it; the
@@ -345,6 +382,17 @@ module Fp
       get("/api/projects/#{project_id}/parity", params)
     end
 
+    # GET /projects/:project_id/parity?include_drafts=true — the same report plus a
+    # top-level `drafts` array: never-approved drafts with their cells resolved from
+    # evidence. Informational only; the server never gates on it (Fizzy #1786). Read by
+    # `fp coverage`, `fp list --status draft --gaps` and `fp check --include-drafts`.
+    def get_parity_with_drafts(project_id, level: nil, surface: nil)
+      params = { include_drafts: 'true' }
+      params[:level] = level if level
+      params[:surface] = surface if surface
+      get("/api/projects/#{project_id}/parity", params)
+    end
+
     # POST /projects/:project_id/parity/preview — the pull-request gate.
     #
     # Evaluates JUnit results as an overlay on the stored grid *without persisting them*,
@@ -513,7 +561,7 @@ module Fp
       http.read_timeout = 30
 
       response = http.request(request)
-      parse_response(response)
+      parse_response(response, uri)
     rescue Net::OpenTimeout, Net::ReadTimeout => e
       { ok: false, error: "Request timed out: #{e.message}", status: 0 }
     rescue SocketError, Errno::ECONNREFUSED => e
@@ -522,13 +570,20 @@ module Fp
       { ok: false, error: "Request failed: #{e.message}", status: 0 }
     end
 
-    def parse_response(response)
+    def parse_response(response, uri = nil)
       body = response.body
       status = response.code.to_i
 
       # Try to parse as JSON
       data = JSON.parse(body) rescue nil
 
+      # A success that isn't JSON is almost always the web app answering in the API's
+      # place — FP_API_URL set to the site rather than its api host — and every command
+      # used to crash on it with "undefined method '[]' for nil" (Fizzy #1446).
+      if status >= 200 && status < 300 && data.nil? && !body.to_s.strip.empty?
+        return { ok: false, status: status, error: not_the_api_message(uri) }
+      end
+
       if status >= 200 && status < 300
         { ok: true, data: data, status: status }
       else
@@ -544,5 +599,27 @@ module Fp
         result
       end
     end
+
+    def not_the_api_message(uri)
+      origin = uri ? "#{uri.scheme}://#{uri.host}" : @base_url
+      message = +"#{origin} answered with a web page, not the FeatureParity API. " \
+                 'Point fp at the API host instead (check it with `fp whoami`).'
+      suggestion = api_host_for(uri&.host)
+      message << " Did you mean https://#{suggestion}? (export FP_API_URL=https://#{suggestion})" if suggestion
+      message
+    end
+
+    # The API host that sits beside a web-app host: featureparity.dev → api.featureparity.dev,
+    # an ephemeral <env>.dev.featureparity.dev → api-<env>.dev.featureparity.dev.
+    def api_host_for(host)
+      return nil if host.nil? || host.start_with?('api.', 'api-')
+      return nil unless host.end_with?('featureparity.dev')
+
+      labels = host.split('.')
+      return "api.#{host}" if labels.length <= 2
+      return "api.#{host}" if labels.first == 'dev' || labels.first == 'staging'
+
+      "api-#{host}"
+    end
   end
 end

data/lib/fp/commands/analyze.rb

@@ -153,6 +153,7 @@ module Fp
           'duplicate_of' => issues.find { |i| i['type'] == 'duplicate' }&.dig('duplicate_of'),
           'conflicts' => (analysis && analysis['conflicts']) || [],
           'suggestions' => (analysis && analysis['suggestions']) || [],
+          'warrants_requirement' => analysis && analysis['warrants_requirement'],
           'error' => error
         }
       end
@@ -199,6 +200,8 @@ module Fp
         end
         puts "    fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
         puts "    issues: #{entry['issues'].map { |i| i['type'] }.join(', ')}" unless entry['issues'].empty?
+        warrants = warrants_line(entry['warrants_requirement'])
+        puts "    #{warrants}" if warrants && entry['warrants_requirement']['judgment'] == false
         puts "    error: #{entry['error']}" if entry['error']
       end
 
@@ -206,6 +209,8 @@ module Fp
         puts "#{entry['slug']} — #{entry['title']}"
         puts "  verdict: #{entry['verdict'] || '(none)'}   suggested: #{ACTIONS[entry['action']]}"
         puts "  superseded by: #{entry['duplicate_of']}" if entry['duplicate_of']
+        warrants = warrants_line(entry['warrants_requirement'])
+        puts "  #{warrants}" if warrants
         puts "  fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
         entry['issues'].each { |i| puts "  issue: #{i['type']}" }
         entry['conflicts'].each do |c|
@@ -215,6 +220,18 @@ module Fp
         puts "  error: #{entry['error']}" if entry['error']
       end
 
+      # The analyzer's yes/no on whether the concept deserves to be a requirement at all.
+      # A "no" carries its reason so a human can decide to withdraw it — the CLI only
+      # reports it; nothing is withdrawn or proposed on the strength of the judgment.
+      def warrants_line(warrants)
+        return nil unless warrants.is_a?(Hash) && [true, false].include?(warrants['judgment'])
+
+        line = "warrants a requirement: #{warrants['judgment'] ? 'yes' : 'no'}"
+        line += " (confidence #{(warrants['confidence'].to_f * 100).round}%)" unless warrants['confidence'].nil?
+        line += " — #{warrants['reason']}" if !warrants['judgment'] && !warrants['reason'].to_s.empty?
+        line
+      end
+
       def progress(message)
         warn message unless output.json?
       end

data/lib/fp/commands/base.rb

@@ -202,12 +202,28 @@ module Fp
 
         unless project
           output.error("Project '#{project_slug_or_id}' not found")
+          hint = config&.environment_mismatch_hint
+          output.error(hint) if hint
           exit 1
         end
 
         project['id']
       end
 
+      # One line on stderr before a command writes to a project, when the API it's about
+      # to write to isn't production. FP_PROFILE / FP_API_URL left over in a shell put an
+      # agent's new project on a dev environment with nothing to say so (Fizzy #1786).
+      # Stderr keeps --json output parseable; it never stops the command.
+      def warn_if_not_production!
+        env = config&.environment
+        return if env.nil? || env == 'production'
+
+        profile = config.profile_name
+        via = profile ? " (profile '#{profile}')" : ''
+        $stderr.puts "⚠ Writing to the '#{env}' environment at #{config.api_url}#{via}, not production. " \
+                     'Run `fp whoami` to see where that comes from.'
+      end
+
       def require_flag(opts, flag, message = nil)
         unless opts[flag]
           message ||= "--#{flag.to_s.tr('_', '-')} is required"

data/lib/fp/commands/check.rb

@@ -51,15 +51,17 @@ module Fp
       help_flag :surface, 'Gate a single surface'
       help_flag :test_type, 'Gate a single test type'
       help_flag :level, 'Override the enforcement level for this run (off/regression/covered/strict)'
-      help_flag :junit, "Gate the branch on this run's results, overlaid on the grid (repeatable, one per surface)"
+      help_flag :junit, "Gate the branch on this run's results (JUnit XML or RSpec JSON), overlaid on the grid (repeatable, one per surface)"
       help_flag :base_dir, "Where the report's relative test-file paths resolve from"
       help_flag :pr, 'With --junit: this run is a pull request — fail only on parity it makes worse, ' \
                      'not on what the default branch already owes (optionally the PR URL)'
       help_flag :warn_only, 'Report violations but still exit 0'
+      help_flag :include_drafts, 'Also show draft coverage after the verdict (never changes the exit code)'
       help_example 'fp check', 'Gate on recorded state (project from .featureparity.yml)'
       help_example 'fp check --surface api --junit junit.xml', 'Gate a default-branch run on its own results'
       help_example 'fp check --surface api --junit junit.xml --pr', 'Gate a pull request on what it changes'
       help_example 'fp check --warn-only --json'
+      help_example 'fp check --include-drafts', 'Onboarding: which drafts have evidence, which have none'
       help_note "Exit 0 = passed, 1 = violations (or request failed). The level lives on the project\n" \
                 'server-side; --level only overrides this one run.'
 
@@ -73,7 +75,8 @@ module Fp
         # `--pr` alone is true; `--pr <url>` carries the URL. Not :boolean on purpose, so
         # the parser takes a following value when one is given.
         pr: :string,
-        warn_only: :boolean
+        warn_only: :boolean,
+        include_drafts: :boolean
       }.freeze
 
       # How many inherited violations to list before summarising the rest. They are
@@ -103,7 +106,9 @@ module Fp
         project_id = resolve_project_id(project_slug)
 
         result =
-          if junit_paths.empty?
+          if junit_paths.empty? && opts[:include_drafts]
+            client.get_parity_with_drafts(project_id, level: level, surface: surface)
+          elsif junit_paths.empty?
             client.get_parity(project_id, level: level, surface: surface)
           else
             preview(project_id, junit_paths, surface, level, opts)
@@ -125,7 +130,12 @@ module Fp
                'this verdict counts every violation, including those the default branch already has.'
         end
 
+        # Draft coverage rides along when asked for. Informational only: it is added after
+        # the verdict was decided and never feeds `passed` (Fizzy #1786).
+        report = report.merge('drafts' => draft_rows(project_id, level, surface, report)) if opts[:include_drafts]
+
         render(report, violations, passed, project_slug, opts)
+        print_drafts(report) if opts[:include_drafts] && !output.json?
 
         # A failing gate is the whole point of the command, so it must be the exit code
         # and not just something printed. --warn-only downgrades it to advisory.
@@ -134,6 +144,30 @@ module Fp
 
       private
 
+      # The standing read already carries `drafts` when asked for. The preview endpoint
+      # doesn't, so a --junit run reads them from the standing report instead; drafts are
+      # recorded state either way. A failed or too-old read is a warning, never a failed
+      # gate, because drafts can't change the verdict.
+      def draft_rows(project_id, level, surface, report)
+        return report['drafts'] if report.key?('drafts')
+
+        result = client.get_parity_with_drafts(project_id, level: level, surface: surface)
+        drafts = result[:ok] ? (result[:data]['parity'] || {})['drafts'] : nil
+        if drafts.nil?
+          warn 'Warning: draft coverage is unavailable from this API; the verdict is unaffected.'
+          return []
+        end
+        drafts
+      end
+
+      def print_drafts(report)
+        drafts = report['drafts'] || []
+        puts
+        puts "Draft coverage (#{drafts.size} draft(s), not gated):"
+        Coverage.print_drafts(output, drafts, report['surfaces'] || [])
+        Coverage.print_untested(Coverage.untested(drafts)) unless drafts.empty?
+      end
+
       # Preview mode needs to know which surface the results belong to, because the
       # server uses it to decide which cells the run had a chance to cover — and
       # therefore which vanished tests it may legitimately flag.
@@ -162,7 +196,7 @@ module Fp
         client.preview_parity(
           project_id,
           surface: surface,
-          junit_xmls: junit_paths.map { |p| File.read(p) },
+          junit_xmls: junit_paths.map { |p| Fp::JUnit.read_xml(p) },
           level: level,
           results: resolve_results(junit_paths, surface, opts),
           pull_request: !!opts[:pr],

data/lib/fp/commands/ci_report.rb

@@ -57,7 +57,7 @@ module Fp
       help_flag :test_type, 'Default test kind for markers that pin none'
       help_flag :ci_url, 'CI run URL to record on the evidence'
       help_flag :pr, "Mark this as a PR's CI: passing tests recorded as pr_passing, no merged evidence demoted"
-      help_flag :junit, 'JUnit XML report (repeatable to combine a surface split across shards)'
+      help_flag :junit, 'JUnit XML report, or RSpec `--format json` output (repeatable to combine a surface split across shards)'
       help_flag :base_dir, "Where the report's relative test-file paths resolve from (e.g. frontend)"
       help_flag :repo, 'Repository the tests live in (org/repo)'
       help_flag :sha, 'Checkout commit SHA'
@@ -127,7 +127,7 @@ module Fp
           totals[:unmarked_failures].concat(resolved[:unmarked_failures])
           totals[:test_revisions] += test_revisions.length
 
-          { path: path, xml: File.read(path), results: results, test_revisions: test_revisions }
+          { path: path, xml: Fp::JUnit.read_xml(path), results: results, test_revisions: test_revisions }
         end
 
         # One surface run may be split across several reports (unit + e2e, shards, etc.).

data/lib/fp/commands/comment.rb

@@ -17,7 +17,7 @@ module Fp
         source_type: :string, source_url: :string, source_context: :string
       }.freeze
 
-      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
+      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat repo_scan].freeze
 
       help_summary "Comment on a requirement's open change proposal"
       help_usage 'fp comment <slug> --body "..." --project <slug>'

data/lib/fp/commands/comments.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp comments <slug>` — the team's conversation on a requirement (Fizzy #1494).
+    #
+    # Without --body it prints the comments, oldest first. With --body it posts one, and
+    # --tag names who to tag: a teammate by email or name, or one of the team's agents by
+    # name or key name. Tagged people are emailed; each tagged agent fires the project's
+    # `requirement.agent_mentioned` webhooks, so whatever runs that agent can pick it up.
+    #
+    # Not to be confused with `fp comment`, which threads a comment onto a requirement's
+    # open change *proposal*.
+    class Comments < Base
+      KNOWN_FLAGS = { project: :string, body: :string, tag: :string }.freeze
+
+      help_summary "Read or post the team's comments on a requirement, tagging people or agents"
+      help_usage 'fp comments <slug> [--body "..." [--tag <who>,<who>]] --project <slug>'
+      help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :body, 'Post this comment (omit to list the comments)'
+      help_flag :tag, 'Comma-separated people (email or name) or agents (name or key name) to tag'
+      help_example 'fp comments print_qr --project stowzilla'
+      help_example 'fp comments print_qr --body "The redesign dropped this screen — retire it?" --tag andy@example.com'
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+
+        slug = positional.first
+        unless slug
+          output.error('Requirement slug is required. Usage: fp comments <slug> [--body "..."] [--project <project>]')
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
+        requirement = find_requirement!(project_id, slug)
+        listing = fetch!(client.list_requirement_comments(requirement['id']))
+
+        if opts[:body].nil?
+          print_comments(listing, slug)
+        else
+          post_comment(requirement, listing, opts, slug)
+        end
+      end
+
+      private
+
+      def post_comment(requirement, listing, opts, slug)
+        body = opts[:body].to_s
+        if body.strip.empty?
+          output.error('A comment needs some text. Pass --body "...".')
+          exit 1
+        end
+
+        people, agents = resolve_tags(opts[:tag], listing)
+        data = fetch!(client.comment_on_requirement(requirement['id'],
+                                                    body: body,
+                                                    mentions: people.map { |p| p['email'] },
+                                                    agent_mentions: agents.map { |a| a['id'] }))
+        comment = data['comment'] || {}
+
+        output.success(data) do
+          puts "Commented on '#{slug}'."
+          puts
+          print_comment(comment)
+          tagged_people = Array(comment['mentions']).map { |m| m['name'] }
+          tagged_agents = Array(comment['agent_mentions']).map { |m| m['name'] }
+          puts "#{tagged_people.join(', ')} will get an email." unless tagged_people.empty?
+          puts "#{tagged_agents.join(', ')} will be notified through the project's webhooks." unless tagged_agents.empty?
+        end
+      end
+
+      # Each --tag matches exactly one person (email or name) or agent (name or key
+      # name), case-insensitively. Unknown or ambiguous tags stop the command rather
+      # than post a comment that silently tags nobody.
+      def resolve_tags(raw, listing)
+        people = []
+        agents = []
+        raw.to_s.split(',').map(&:strip).reject(&:empty?).each do |tag|
+          wanted = tag.delete_prefix('@').downcase
+          person_hits = Array(listing['mentionable']).select do |p|
+            [p['email'], p['name']].compact.map(&:downcase).include?(wanted)
+          end
+          agent_hits = Array(listing['mentionable_agents']).select do |a|
+            [a['name'], a['key_name']].compact.map(&:downcase).include?(wanted)
+          end
+          hits = person_hits + agent_hits
+          if hits.empty?
+            output.error("Nobody on this project's team matches '#{tag}'. Run `fp comments <slug>` to see who can be tagged.")
+            exit 1
+          elsif hits.size > 1
+            output.error("'#{tag}' matches more than one person or agent; use an email or key name instead.")
+            exit 1
+          end
+          person_hits.empty? ? agents << agent_hits.first : people << person_hits.first
+        end
+        [people, agents]
+      end
+
+      def print_comments(listing, slug)
+        comments = Array(listing['comments'])
+        output.success(listing) do
+          puts "Comments on '#{slug}'"
+          puts
+          if comments.empty?
+            puts '  (no comments yet)'
+          else
+            comments.each { |comment| print_comment(comment) }
+          end
+          print_taggable(listing)
+        end
+      end
+
+      def print_comment(comment)
+        kind = comment['actor_kind'] == 'agent' ? ' (agent)' : ''
+        puts "* #{comment['actor_name'] || comment['actor']}#{kind} at #{comment['recorded_at']}"
+        comment['body'].to_s.each_line { |line| puts "  > #{line.chomp}" }
+        tags = Array(comment['mentions']) + Array(comment['agent_mentions'])
+        puts "  tagged: #{tags.map { |t| t['name'] }.join(', ')}" unless tags.empty?
+        puts
+      end
+
+      def print_taggable(listing)
+        people = Array(listing['mentionable']).map { |p| "#{p['name']} <#{p['email']}>" }
+        agents = Array(listing['mentionable_agents']).map { |a| "#{a['name']} (#{a['key_name']}, #{a['owner_name']}'s agent)" }
+        return if people.empty? && agents.empty?
+
+        puts 'Can be tagged with --tag:'
+        people.each { |p| puts "  #{p}" }
+        agents.each { |a| puts "  #{a}" }
+      end
+
+      def find_requirement!(project_id, slug)
+        fetch!(client.find_requirement_by_slug(project_id, slug))['requirement']
+      end
+
+      def fetch!(result)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+        result[:data]
+      end
+    end
+  end
+end