featureparity 0.0.15 → 0.0.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efbe901394a8f97be6d1340a877ecafa6a8151453ed5a78708e91b6e40af1fe1
-  data.tar.gz: 51358f9c7907107f3744775e414f175a1206ace2a104b44dcfcee4723a13e8e4
+  metadata.gz: d20b326add84bbad1fc34a9b2b41c70216f7e9f2797f47cc9cba9f4293d27f1e
+  data.tar.gz: ae9721b86841174ee64f1925b0878e5ca5b5e34ea1f467ea0275887526515695
 SHA512:
-  metadata.gz: 16067e82a07cac5e0bf5df3548950ff5d966e8f822ba6315740f474a9d50e17fa25f99adfc9fc4a58a2af66bcd03f3e0edce7e9ab143e05fb6f4b9c2fe2e013e
-  data.tar.gz: 8f58e25f9465851931d0d763f1655b56112cd7899e919af8ee5bf0975fc6ec090c631fc42d993f76dce210468ce4d766cea2c1575b62282f35a969f2124e7530
+  metadata.gz: 87aa7b100433761979acec4c6a3f66c665757ebd77924cf1bab483861a1855be92acba93d3a6bd0e2f0cdc9daf9c887380a808eab96c467c3a41ee4e665f8bb0
+  data.tar.gz: 640c69700985e08ce0c6aec534d42d544db0d04771ae9f9be254e24aca3952cbbff7f52456c1c7b506c8bbf5e6a3d3b54c8c7959d6575d159d19cff5cad69c0b

data/lib/fp/cli.rb

@@ -11,9 +11,12 @@ module Fp
       'show' => Commands::Show,
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
+      'comment' => Commands::Comment,
       'history' => Commands::History,
+      'changes' => Commands::Changes,
       'report' => Commands::Report,
       'ci-report' => Commands::CiReport,
+      'changed-tests' => Commands::ChangedTests,
       'check' => Commands::Check,
       'matrix' => Commands::Matrix,
       'export' => Commands::Export,

data/lib/fp/client.rb

@@ -98,6 +98,14 @@ module Fp
       put("/api/requirements/#{id}", params)
     end
 
+    # GET /projects/:project_id/requirement_changes — project-wide audit activity,
+    # optionally narrowed to the exact work-item URL that prompted it.
+    def list_project_requirement_changes(project_id, source_url: nil)
+      params = {}
+      params[:source_url] = source_url if source_url
+      get("/api/projects/#{project_id}/requirement_changes", params)
+    end
+
     # GET /requirements/:id/changes
     #
     # A requirement's change history: what it was, what changed, who changed it, and
@@ -122,6 +130,15 @@ module Fp
       put("/api/requirements/#{requirement_id}/changes/#{change_id}", params)
     end
 
+    # POST /requirements/:id/changes/:change_id/comment
+    #
+    # Thread a comment onto the open proposal. The single-open-proposal rule means a
+    # second agent can't open a rival change; this lets it raise its concern *on* the
+    # proposal a human is about to review instead of hitting a dead-end 409.
+    def comment_requirement_change(requirement_id, change_id, params)
+      post("/api/requirements/#{requirement_id}/changes/#{change_id}/comment", params)
+    end
+
     # GET /projects/:project_id/evidence — the receipts already filed for a project,
     # optionally narrowed to one requirement slug and/or surface.
     def list_evidence(project_id, slug: nil, surface: nil)
@@ -152,7 +169,7 @@ module Fp
     # only do that by fetching the test files from GitHub, which fails silently on a
     # private repo, so resolved results are always sent when we have them.
     def ingest_ci_results(project_id, ci_url:, surface:, junit_xml:, pr_url: nil, results: nil,
-                          unmarked_failures: nil)
+                          test_revisions: nil, unmarked_failures: nil)
       body = {
         ci_url: ci_url,
         surface: surface,
@@ -161,6 +178,9 @@ module Fp
       # Only send pr_url when set, so a merged-branch run stays a plain ingest.
       body[:pr_url] = pr_url if pr_url && !pr_url.empty?
       body[:results] = results if results && !results.empty?
+      # Testcase-level source receipts stay separate from aggregate Evidence outcomes:
+      # several tests may back one cell, and each can change independently.
+      body[:test_revisions] = test_revisions if test_revisions && !test_revisions.empty?
       # Loose ends: failing tests with no fp:<slug> marker. The server stores them so the
       # matrix can surface a red suite whose failures aren't bound to any requirement.
       body[:unmarked_failures] = unmarked_failures if unmarked_failures && !unmarked_failures.empty?
@@ -168,6 +188,27 @@ module Fp
       post("/api/projects/#{project_id}/ci_results", body)
     end
 
+    # GET /projects/:project_id/changed_test_findings — every unresolved audit finding.
+    def list_changed_test_findings(project_id, surface: nil, test_type: nil)
+      params = {}
+      params[:surface] = surface if surface
+      params[:test_type] = test_type if test_type
+      get("/api/projects/#{project_id}/changed_test_findings", params)
+    end
+
+    # POST an assessment for the exact candidate fingerprint the agent inspected.
+    def assess_changed_test_finding(project_id, finding_id, classification:, explanation:,
+                                    candidate_fingerprint:)
+      post(
+        "/api/projects/#{project_id}/changed_test_findings/#{finding_id}/assessment",
+        {
+          classification: classification,
+          explanation: explanation,
+          candidate_fingerprint: candidate_fingerprint
+        }
+      )
+    end
+
     # GET /projects/:project_id/parity — the computed parity grid and gate verdict.
     #
     # This replaces the old get_matrix/get_gaps stubs, which pointed at /api/matrix
@@ -197,7 +238,10 @@ module Fp
     # ingest_ci_results). Sending them is what lets a surface whose repo isn't registered
     # — or a private one the server can't read — be previewed at all.
     def preview_parity(project_id, surface:, junit_xmls:, level: nil, results: nil)
-      body = { surface: surface, junit_xmls: Array(junit_xmls) }
+      # Older API deployments read `surface_filter` for report scoping while `surface`
+      # identifies the run's overlay. Send both during the rollout; current servers use
+      # `surface` for both meanings.
+      body = { surface: surface, surface_filter: surface, junit_xmls: Array(junit_xmls) }
       body[:results] = results if results && !results.empty?
       body[:level] = level if level
       post("/api/projects/#{project_id}/parity/preview", body)
@@ -352,7 +396,11 @@ module Fp
                         else
                           body.to_s.empty? ? "HTTP #{status}" : body.to_s[0..200]
                         end
-        { ok: false, error: error_message, status: status }
+        result = { ok: false, error: error_message, status: status }
+        # Carry structured error details (e.g. the open proposal behind a 409) so a
+        # command can act on them instead of only printing the message.
+        result[:details] = data['details'] if data.is_a?(Hash) && data.key?('details')
+        result
       end
     end
   end

data/lib/fp/commands/changed_tests.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # Lists CI-detected revisions to bound tests and records an agent's assessment of an
+    # exact candidate fingerprint.
+    class ChangedTests < Base
+      CLASSIFICATIONS = %w[still_proves no_longer_proves uncertain].freeze
+      KNOWN_FLAGS = {
+        project: :string,
+        surface: :string,
+        test_type: :string,
+        classification: :string,
+        explanation: :string,
+        candidate_fingerprint: :string
+      }.freeze
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+
+        if positional.first == 'assess'
+          assess(project_id, positional[1], opts)
+        else
+          list(project_id, opts)
+        end
+      end
+
+      private
+
+      def list(project_id, opts)
+        result = client.list_changed_test_findings(
+          project_id,
+          surface: opts[:surface],
+          test_type: opts[:test_type]
+        )
+        fail_result(result) unless result[:ok]
+
+        data = result[:data] || {}
+        findings = data['changed_test_findings'] || []
+        output.success(data) do
+          if findings.empty?
+            puts 'No unresolved changed-test findings.'
+            next
+          end
+
+          puts "#{findings.length} unresolved changed-test audit finding(s):"
+          findings.each { |finding| print_finding(finding) }
+        end
+      end
+
+      def assess(project_id, finding_id, opts)
+        if finding_id.nil? || finding_id.empty?
+          output.error('Finding id is required. Usage: fp changed-tests assess <id> ...')
+          exit 1
+        end
+
+        classification = opts[:classification].to_s.tr('-', '_')
+        unless CLASSIFICATIONS.include?(classification)
+          output.error("--classification must be one of: #{CLASSIFICATIONS.join(', ')}")
+          exit 1
+        end
+        require_flag(opts, :candidate_fingerprint)
+        require_flag(opts, :explanation)
+        if opts[:explanation].to_s.strip.empty?
+          output.error('--explanation must not be blank')
+          exit 1
+        end
+
+        result = client.assess_changed_test_finding(
+          project_id,
+          finding_id,
+          classification: classification,
+          explanation: opts[:explanation],
+          candidate_fingerprint: opts[:candidate_fingerprint]
+        )
+        fail_result(result) unless result[:ok]
+
+        data = result[:data] || {}
+        output.success(data) do
+          finding = data['changed_test_finding'] || {}
+          puts "Recorded #{classification.tr('_', ' ')} for changed-test finding #{finding_id}."
+          puts "Status: #{finding['status']}"
+          puts 'The CI outcome and requirement wording were not changed.'
+        end
+      end
+
+      def print_finding(finding)
+        requirement = finding['requirement'] || {}
+        testcase = finding['testcase'] || {}
+        accepted = finding['accepted'] || {}
+        candidate = finding['candidate'] || {}
+        assessment = finding['assessment'] || {}
+
+        puts
+        puts "#{finding['id']}  #{requirement['slug']}  [#{finding['surface']}#{type_suffix(finding)}]"
+        puts "  Requirement: #{requirement['title']}"
+        puts "  Acceptance:  #{requirement['acceptance']}"
+        puts "  Testcase:    #{testcase['name']} (#{testcase['outcome']})"
+        puts "  Scope:       #{finding['fingerprint_scope']}"
+        puts "  Accepted:    #{revision_text(accepted)}"
+        puts "  Candidate:   #{revision_text(candidate)}"
+        puts "  Assessment:  #{assessment['classification']}: #{assessment['explanation']}" unless assessment.empty?
+        puts '  Assess:      fp changed-tests assess ' \
+             "#{finding['id']} --candidate-fingerprint #{candidate['fingerprint']} " \
+             '--classification still_proves|no_longer_proves|uncertain --explanation "..."'
+      end
+
+      def type_suffix(finding)
+        type = finding['test_type'].to_s
+        type.empty? || type == 'unspecified' ? '' : ":#{type}"
+      end
+
+      def revision_text(revision)
+        location = revision['source_url'] || [revision['source_file'], revision['start_line']].compact.join(':')
+        "#{revision['fingerprint']} @ #{revision['commit_sha']} #{location}".strip
+      end
+
+      def fail_result(result)
+        output.error(result[:error], status: result[:status])
+        exit 1
+      end
+    end
+  end
+end

data/lib/fp/commands/changes.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+module Fp
+  module Commands
+    # `fp changes` lists requirement activity associated with a work item. In GitHub
+    # Actions it can discover source URLs from the pull request body, append a job
+    # summary, and keep a managed table in the pull request description itself.
+    class Changes < Base
+      PR_SECTION_BEGIN = '<!-- feature-parity:requirement-changes:begin -->'
+      PR_SECTION_END = '<!-- feature-parity:requirement-changes:end -->'
+
+      KNOWN_FLAGS = {
+        project: :string,
+        source_url: :string,
+        github_summary: :boolean,
+        github_pr: :boolean
+      }.freeze
+
+      TYPE_LABELS = {
+        'created' => 'Created',
+        'updated' => 'Edited',
+        'activated' => 'Activated',
+        'archived' => 'Archived',
+        'rejected' => 'Rejected',
+        'destroyed' => 'Deleted',
+        'change_proposed' => 'Modification proposed',
+        'removal_proposed' => 'Removal proposed',
+        'change_approved' => 'Change approved',
+        'change_rejected' => 'Change rejected'
+      }.freeze
+
+      def run(args)
+        explicit_urls, rest = extract_repeated(args, '--source-url')
+        opts, = parse_flags(rest, KNOWN_FLAGS)
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+        @github_pull_request = fetch_github_pull_request if opts[:github_pr]
+
+        source_urls = explicit_urls.map(&:strip).reject(&:empty?).uniq
+        source_urls = github_source_urls if source_urls.empty?
+
+        data = {
+          project: project_slug,
+          source_urls: source_urls,
+          requirement_changes: [],
+          source_detected: !source_urls.empty?
+        }
+
+        if source_urls.any?
+          project_id = resolve_project_id(project_slug)
+          data[:requirement_changes] = fetch_changes(project_id, source_urls)
+        end
+
+        markdown = render_markdown(data)
+        destinations = []
+
+        if opts[:github_summary]
+          append_github_summary(markdown)
+          destinations << ENV['GITHUB_STEP_SUMMARY']
+        end
+        if opts[:github_pr]
+          update_github_pull_request(markdown)
+          destinations << 'the pull request description'
+        end
+
+        output.success(data) do
+          if destinations.any?
+            puts "FeatureParity requirement-change table updated in #{destinations.join(' and ')}."
+          else
+            puts markdown
+          end
+        end
+      end
+
+      private
+
+      def fetch_changes(project_id, source_urls)
+        changes = []
+
+        source_urls.each do |source_url|
+          result = client.list_project_requirement_changes(project_id, source_url: source_url)
+          if [400, 403, 404].include?(result[:status].to_i) && result[:error].to_s.match?(/bad request|not found/i)
+            return legacy_changes(project_id, source_urls)
+          end
+
+          unless result[:ok]
+            output.error(result[:error], status: result[:status])
+            exit 1
+          end
+
+          changes.concat(result[:data]['requirement_changes'] || [])
+        end
+
+        collapse_to_latest_per_requirement(
+          changes.uniq { |change| change['id'] }
+                 .sort_by { |change| change['recorded_at'].to_s }
+                 .reverse
+        )
+      end
+
+      # Option A: one row per requirement. A requirement whose creation and a later
+      # modification proposal both trace to the same work item would otherwise appear
+      # twice, which reads as a duplicate. We keep only the most recent event per
+      # requirement, so the table answers "where does each requirement stand now?"
+      # rather than replaying its whole timeline (that lives in `fp history <slug>`).
+      def collapse_to_latest_per_requirement(changes)
+        changes.each_with_object({}) do |change, latest|
+          key = change['slug'] || change['requirement_path'] || change['id']
+          latest[key] ||= change
+        end.values
+      end
+
+      # Compatibility with an API that predates the project activity endpoint. This is
+      # especially useful while a CLI/API release is rolling out: requirements whose own
+      # source matches the work item, plus every open proposal, are inspected through the
+      # existing per-requirement history endpoint. Once the endpoint is deployed, its
+      # ProjectIndex also covers reviewed and deleted activity without this bounded scan.
+      def legacy_changes(project_id, source_urls)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        requirements = result[:data]['requirements'] || []
+        candidates = requirements.select do |requirement|
+          source_urls.include?(requirement['source_url']) || present?(requirement['pending_change_id'])
+        end
+
+        collapsed = candidates.flat_map do |requirement|
+          history = client.list_requirement_changes(requirement['id'])
+          next [] unless history[:ok]
+
+          (history[:data]['changes'] || []).filter_map do |change|
+            next unless source_urls.include?(change.dig('source', 'url'))
+
+            change.merge(
+              'slug' => requirement['slug'],
+              'title' => requirement['title'],
+              'requirement_status' => requirement['status'],
+              'requirement_path' => "/projects/#{project_id}/requirements/#{requirement['id']}",
+              'review_state' => change.dig('review', 'decision') || (change['pending'] ? 'pending' : requirement['status'])
+            )
+          end
+        end.uniq { |change| change['id'] }
+           .sort_by { |change| change['recorded_at'].to_s }
+           .reverse
+
+        collapse_to_latest_per_requirement(collapsed)
+      end
+
+      def github_source_urls
+        body = if @github_pull_request
+                 @github_pull_request.fetch('body', '').to_s
+               else
+                 github_event.dig('pull_request', 'body').to_s
+               end
+
+        body = body.sub(/#{Regexp.escape(PR_SECTION_BEGIN)}.*?#{Regexp.escape(PR_SECTION_END)}/m, '')
+
+        # Option B: explicit fp-source markers take precedence
+        explicit = body.scan(/fp-source:\s*(https?:\/\/\S+)/i).flatten.map { |url| clean_url(url) }
+        return explicit.uniq if explicit.any?
+
+        # Option A: heuristic detection of ticket-tracker URLs
+        URI.extract(body, %w[http https])
+           .map { |url| clean_url(url) }
+           .select { |url| work_item_url?(url) }
+           .uniq
+      end
+
+      def github_event
+        return @github_event if defined?(@github_event)
+
+        event_path = ENV['GITHUB_EVENT_PATH']
+        @github_event = if present?(event_path) && File.file?(event_path)
+                          JSON.parse(File.read(event_path))
+                        else
+                          {}
+                        end
+      rescue JSON::ParserError
+        @github_event = {}
+      end
+
+      def work_item_url?(url)
+        # Heuristic detection: accept URLs that look like ticket trackers.
+        # Matches paths containing common ticket-tracker segments.
+        url.match?(%r{
+          \Ahttps?://[^/]+           # scheme and host
+          (?:
+            .*/(?:issues|cards|browse|tickets|tasks|work[-_]?items?|bugs?|stories?|features?|pull|merge_requests?|issue|story|_workitems|channels|c|t)/[^\s/]+ |
+            .*/\d+(?:/|\z)           # any path ending in /123 or /123/
+          )
+        }xi)
+      end
+
+      def clean_url(url)
+        url.sub(/[)\]}>.,;:]+\z/, '')
+      end
+
+      def append_github_summary(markdown)
+        path = ENV['GITHUB_STEP_SUMMARY']
+        unless present?(path)
+          output.error('--github-summary requires GITHUB_STEP_SUMMARY (it is set automatically by GitHub Actions)')
+          exit 1
+        end
+
+        File.open(path, 'a') { |file| file.puts(markdown) }
+      end
+
+      def fetch_github_pull_request
+        token, uri = github_credentials
+        response = github_request(Net::HTTP::Get, uri, token)
+        fail_github_request!('read the pull request', response) unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        output.error('GitHub returned an invalid response while reading the pull request')
+        exit 1
+      rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        output.error("Could not read the pull request from GitHub: #{e.message}")
+        exit 1
+      end
+
+      def update_github_pull_request(markdown)
+        current_body = @github_pull_request.fetch('body', '').to_s
+        updated_body = managed_pull_request_body(current_body, markdown)
+        return if updated_body == current_body
+
+        token, uri = github_credentials
+        response = github_request(Net::HTTP::Patch, uri, token, body: { body: updated_body })
+        fail_github_request!('update the pull request description', response) unless response.is_a?(Net::HTTPSuccess)
+      rescue SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        output.error("Could not update the pull request description on GitHub: #{e.message}")
+        exit 1
+      end
+
+      def managed_pull_request_body(body, markdown)
+        section = "#{PR_SECTION_BEGIN}\n#{markdown}\n#{PR_SECTION_END}"
+        begin_count = body.scan(PR_SECTION_BEGIN).length
+        end_count = body.scan(PR_SECTION_END).length
+
+        unless [begin_count, end_count].all? { |count| [0, 1].include?(count) } && begin_count == end_count
+          output.error('The pull request description has malformed or duplicate FeatureParity requirement-change markers')
+          exit 1
+        end
+
+        if begin_count == 1
+          body.sub(/#{Regexp.escape(PR_SECTION_BEGIN)}.*?#{Regexp.escape(PR_SECTION_END)}/m, section)
+        else
+          [body.rstrip, section].reject(&:empty?).join("\n\n") + "\n"
+        end
+      end
+
+      def github_credentials
+        token = ENV['GITHUB_TOKEN']
+        repository = ENV['GITHUB_REPOSITORY'].to_s
+        number = github_event.dig('pull_request', 'number') || github_event['number']
+
+        unless present?(token) && repository.match?(%r{\A[^/]+/[^/]+\z}) && number.to_i.positive?
+          output.error('--github-pr requires GITHUB_TOKEN, GITHUB_REPOSITORY, and a pull_request GITHUB_EVENT_PATH')
+          exit 1
+        end
+
+        owner, repo = repository.split('/', 2).map { |part| URI.encode_www_form_component(part) }
+        api_url = ENV.fetch('GITHUB_API_URL', 'https://api.github.com').sub(%r{/+\z}, '')
+        [token, URI.parse("#{api_url}/repos/#{owner}/#{repo}/pulls/#{number.to_i}")]
+      rescue URI::InvalidURIError
+        output.error('GITHUB_API_URL is not a valid URL')
+        exit 1
+      end
+
+      def github_request(request_class, uri, token, body: nil)
+        request = request_class.new(uri)
+        request['Accept'] = 'application/vnd.github+json'
+        request['Authorization'] = "Bearer #{token}"
+        request['User-Agent'] = 'featureparity-cli'
+        request['X-GitHub-Api-Version'] = '2022-11-28'
+        if body
+          request['Content-Type'] = 'application/json'
+          request.body = JSON.generate(body)
+        end
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          http.request(request)
+        end
+      end
+
+      def fail_github_request!(action, response)
+        details = JSON.parse(response.body).fetch('message', response.body.to_s)
+        output.error("GitHub could not #{action}: #{details}", status: response.code.to_i)
+        exit 1
+      rescue JSON::ParserError
+        output.error("GitHub could not #{action}: HTTP #{response.code}", status: response.code.to_i)
+        exit 1
+      end
+
+      def render_markdown(data)
+        lines = ['## FeatureParity requirement changes', '']
+
+        unless data[:source_detected]
+          lines << '⚠️ No work-item URL was found in the pull request description, so FeatureParity cannot determine which requirement activity belongs to this change.'
+          return lines.join("\n")
+        end
+
+        links = data[:source_urls].map { |url| "[#{markdown_escape(url)}](#{url})" }
+        lines << "Work item#{links.length == 1 ? '' : 's'}: #{links.join(', ')}"
+        lines << ''
+
+        changes = data[:requirement_changes]
+        if changes.empty?
+          lines << 'No requirement changes are recorded for the linked work item(s).'
+          return lines.join("\n")
+        end
+
+        lines << '| Requirement | Change | Review | Actor |'
+        lines << '| --- | --- | --- | --- |'
+        changes.each do |change|
+          lines << "| #{requirement_cell(change)} | #{TYPE_LABELS.fetch(change['type'], change['type'])} | " \
+                   "#{markdown_escape(change['review_state'] || change['requirement_status'] || '—')} | " \
+                   "#{markdown_escape(change['actor'] || '—')} |"
+        end
+        lines << ''
+        lines << '_Open the linked requirement to review its wording, diff, evidence, and decision state._'
+        lines.join("\n")
+      end
+
+      def requirement_cell(change)
+        slug = change['slug'] || 'unknown'
+        title = markdown_escape(change['title'] || slug)
+        path = change['requirement_path']
+        return title unless present?(path)
+
+        "[#{title}](#{web_base_url}#{path})"
+      end
+
+      def web_base_url
+        uri = URI.parse(config.api_url)
+        host = uri.host.to_s.sub(/\Aapi\./, '')
+        "#{uri.scheme || 'https'}://#{host}"
+      rescue URI::InvalidURIError
+        'https://featureparity.dev'
+      end
+
+      def markdown_escape(value)
+        value.to_s.gsub('|', '\\|').gsub("\n", ' ')
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.strip.empty?
+      end
+    end
+  end
+end