featureparity 0.0.16 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd15c5892d88c0202433fd6e11993440f45cd3cb8c754c0c7138309008190cbb
-  data.tar.gz: 356c8c54af360a47639e2dfc6313774247ff93534eb02b6666656f738d69ce70
+  metadata.gz: c4c40ac26de064785c94120334d42b1e5e906803db09ad49e9954be91aa85ed3
+  data.tar.gz: a83874973a35ed0335c58f9fe49b71fb66f4a5ba97e028a806c34929f4e5718f
 SHA512:
-  metadata.gz: d0d96204c4cf14ff9c7f5bbf1930f1ad6f170b11be67651df1cda342c2ad41e53e1a09ea93bed84db620d2c867f26ffbc313fa2d132f7b5b8b474026b4ea9ee8
-  data.tar.gz: c43e169274e9c6484b6e41c2bcb1c5748eaee9dabad8c39f523c7ed30a08f0edaeae3df7637edc799d2089165624108e72fdb517c95d580cc51c1b747064726b
+  metadata.gz: 75f833ce8cbf39c68a0ba50c12bee2f369d3d374ab3d8f2ce3468af433e18af6190b0d17a57a1e102fb1c58da80c8a0dbfea5d0f96bab78f0101f4f47c607aeb
+  data.tar.gz: 30c2e791fdefc1be0b83b13b4823b520d457dcd9c44adcd79b3f403525c338fc25dd73486f4b4388a7a43de641b7b81244116cdced8db5101330bc8b983b4888

data/lib/fp/cli.rb

@@ -11,10 +11,13 @@ module Fp
       'show' => Commands::Show,
       'propose' => Commands::Propose,
       'propose-change' => Commands::ProposeChange,
+      'comment' => Commands::Comment,
       'history' => Commands::History,
+      'analyze' => Commands::Analyze,
       '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

@@ -106,6 +106,21 @@ module Fp
       get("/api/projects/#{project_id}/requirement_changes", params)
     end
 
+    # GET /requirements/:id/analysis — the cached analysis, free to read. `analysis` is
+    # null when none exists or the wording changed since it ran (`stale` says which).
+    def get_requirement_analysis(requirement_id)
+      get("/api/requirements/#{requirement_id}/analysis")
+    end
+
+    # POST /requirements/:id/analyze — run (or return the still-current cached) analysis.
+    # One model call per requirement, which is what keeps it inside the request timeout.
+    def analyze_requirement(requirement_id, force: false, include_conflicts: false)
+      body = {}
+      body[:force] = true if force
+      body[:include_conflicts] = true if include_conflicts
+      post("/api/requirements/#{requirement_id}/analyze", body)
+    end
+
     # GET /requirements/:id/changes
     #
     # A requirement's change history: what it was, what changed, who changed it, and
@@ -130,6 +145,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)
@@ -160,7 +184,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,
@@ -169,6 +193,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?
@@ -176,6 +203,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
@@ -205,7 +253,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)
@@ -238,15 +289,28 @@ module Fp
     end
 
     # POST /requirements/:requirement_id/attachments
-    # Confirm an upload and create the attachment record.
-    def create_attachment(requirement_id, attachment_id:, s3_key:, filename:, content_type:, size_bytes:)
-      post("/api/requirements/#{requirement_id}/attachments", {
+    # Confirm an upload and create the attachment record. Visual evidence may also
+    # carry the surface, capture time, observed deployment, and originating test run.
+    # evidence_key is a direct join to the evidence receipt (surface:repo:test_type).
+    def create_attachment(requirement_id, attachment_id:, s3_key:, filename:, content_type:, size_bytes:,
+                          surface: nil, captured_at: nil, deployed_at: nil, deployment_url: nil,
+                          test_run_url: nil, sha: nil, example_title: nil, evidence_key: nil)
+      body = {
         attachment_id: attachment_id,
         s3_key: s3_key,
         filename: filename,
         content_type: content_type,
         size_bytes: size_bytes
-      })
+      }
+      body[:surface] = surface if surface
+      body[:captured_at] = captured_at if captured_at
+      body[:deployed_at] = deployed_at if deployed_at
+      body[:deployment_url] = deployment_url if deployment_url
+      body[:test_run_url] = test_run_url if test_run_url
+      body[:sha] = sha if sha
+      body[:example_title] = example_title if example_title
+      body[:evidence_key] = evidence_key if evidence_key
+      post("/api/requirements/#{requirement_id}/attachments", body)
     end
 
     # GET /requirements/:requirement_id/attachments/:id
@@ -261,23 +325,24 @@ module Fp
       delete("/api/requirements/#{requirement_id}/attachments/#{attachment_id}")
     end
 
-    # Upload a file to S3 using a presigned URL.
-    # This is called after presign_attachment returns the upload_url.
+    # Upload to S3 using a streaming request. Video evidence can be up to 100 MB;
+    # reading it all into the CLI process would needlessly double memory usage.
     def upload_to_presigned_url(url, file_path, content_type)
       uri = URI.parse(url)
-      file_content = File.binread(file_path)
+      file_size = File.size(file_path)
 
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == 'https'
       http.open_timeout = 30
-      http.read_timeout = 120 # Allow longer for file upload
-
-      request = Net::HTTP::Put.new(uri)
-      request.body = file_content
-      request['Content-Type'] = content_type
-      request['Content-Length'] = file_content.bytesize.to_s
-
-      response = http.request(request)
+      http.read_timeout = 120
+
+      response = File.open(file_path, 'rb') do |file|
+        request = Net::HTTP::Put.new(uri)
+        request.body_stream = file
+        request['Content-Type'] = content_type
+        request['Content-Length'] = file_size.to_s
+        http.request(request)
+      end
       status = response.code.to_i
 
       if status >= 200 && status < 300
@@ -360,7 +425,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/analyze.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp analyze [<slug>]` — a read-only triage sweep of requirement quality.
+    #
+    # Analysis is one model call per requirement, so this walks the catalog client-side,
+    # one request at a time, rather than asking the server to do it all in a single
+    # request (which cannot finish inside the API timeout on a real catalog). Results are
+    # cached server-side, so a requirement whose wording hasn't changed is read back for
+    # free and only new or edited ones cost a call — re-running the sweep is cheap.
+    #
+    # It never files anything. Proposing a change demotes the requirement to draft and
+    # marks its evidence suspect, so sweeping a catalog and proposing on every flag could
+    # put dozens of requirements up for review at once. The report says what *kind* of
+    # follow-up each finding suggests; a human picks which proposals get filed.
+    class Analyze < Base
+      KNOWN_FLAGS = {
+        project: :string,
+        status: :string,
+        conflicts: :boolean,
+        force: :boolean,
+        cached: :boolean
+      }.freeze
+
+      # Server-side findings that mean "this probably shouldn't be its own row".
+      REMOVAL_CHECKS = %w[is_focused_promise].freeze
+
+      ACTIONS = {
+        'conflict' => 'Stop and ask a human — two promises may contradict',
+        'propose_removal' => 'Consider `fp propose-change <slug> --removal` (duplicate, or a fragment of a broader promise)',
+        'needs_human' => 'Not clearly a product promise — a human decides whether it belongs',
+        'propose_change' => 'Consider `fp propose-change <slug>` to fix the wording',
+        'in_review' => 'A change is already awaiting review — skipped',
+        'not_analyzed' => 'No current analysis (run without --cached to analyze)',
+        'error' => 'Analysis failed',
+        'ok' => 'Nothing to act on'
+      }.freeze
+
+      ORDER = %w[conflict propose_removal needs_human propose_change in_review not_analyzed error ok].freeze
+
+      def run(args)
+        opts, positional = parse_flags(args, KNOWN_FLAGS)
+        require_project!(opts)
+
+        project_id = resolve_project_id(opts[:project])
+        requirements = select_requirements(project_id, positional.first, opts)
+
+        entries = requirements.map { |r| analyze_one(r, opts, requirements.length > 1) }
+        report = build_report(entries)
+
+        output.success(report) { print_report(report) }
+      end
+
+      private
+
+      def select_requirements(project_id, slug, opts)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        all = result[:data]['requirements'] || []
+        if slug
+          found = all.select { |r| r['slug'] == slug }
+          if found.empty?
+            output.error("Requirement '#{slug}' not found in project")
+            exit 1
+          end
+          return found
+        end
+
+        statuses = (opts[:status] || 'active,draft').split(',').map(&:strip)
+        all.select { |r| statuses.include?(r['status']) }
+      end
+
+      def analyze_one(requirement, opts, sweeping)
+        slug = requirement['slug']
+        if requirement['pending_change_kind'].to_s != ''
+          return entry(requirement, 'in_review', nil)
+        end
+
+        progress("#{slug} ...") if sweeping
+        analysis = cached_analysis(requirement)
+
+        if analysis.nil? || opts[:force] || opts[:conflicts] && analysis['conflicts'].nil?
+          return entry(requirement, 'not_analyzed', nil) if opts[:cached]
+
+          result = client.analyze_requirement(requirement['id'], force: opts[:force],
+                                                                 include_conflicts: opts[:conflicts])
+          unless result[:ok]
+            # Without access (or without the analyzer) every call would fail the same way.
+            if [401, 402, 403, 503].include?(result[:status])
+              output.error(result[:error], status: result[:status])
+              exit 1
+            end
+            return entry(requirement, 'error', nil, error: result[:error])
+          end
+          analysis = result[:data]['analysis']
+        end
+
+        entry(requirement, classify(analysis), analysis)
+      end
+
+      # Free read of whatever is already cached and current; nil if there is none.
+      def cached_analysis(requirement)
+        result = client.get_requirement_analysis(requirement['id'])
+        result[:ok] ? result[:data]['analysis'] : nil
+      end
+
+      # Which kind of follow-up a finding suggests. Precedence matters: a possible
+      # contradiction outranks everything because it is a product decision, not an edit.
+      def classify(analysis)
+        return 'conflict' unless (analysis['conflicts'] || []).empty?
+
+        issues = analysis['issues'] || []
+        failed = failed_legitimacy_checks(analysis)
+
+        return 'propose_removal' if issues.any? { |i| i['type'] == 'duplicate' } ||
+                                    (failed & REMOVAL_CHECKS).any?
+        return 'needs_human' if analysis['verdict'] == 'questionable'
+        return 'propose_change' if analysis['verdict'] == 'needs_work' || !issues.empty?
+
+        'ok'
+      end
+
+      def failed_legitimacy_checks(analysis)
+        checks = analysis.dig('legitimacy', 'checks') || {}
+        checks.reject { |_name, c| c['passes'] }.keys
+      end
+
+      def entry(requirement, action, analysis, error: nil)
+        issues = (analysis && analysis['issues']) || []
+        {
+          'slug' => requirement['slug'],
+          'title' => requirement['title'],
+          'status' => requirement['status'],
+          'action' => action,
+          'verdict' => analysis && analysis['verdict'],
+          'failed_checks' => analysis ? failed_legitimacy_checks(analysis) : [],
+          'issues' => issues,
+          'duplicate_of' => issues.find { |i| i['type'] == 'duplicate' }&.dig('duplicate_of'),
+          'conflicts' => (analysis && analysis['conflicts']) || [],
+          'suggestions' => (analysis && analysis['suggestions']) || [],
+          'error' => error
+        }
+      end
+
+      def build_report(entries)
+        counts = entries.group_by { |e| e['action'] }.transform_values(&:length)
+        { 'analyzed' => entries.length, 'counts' => counts, 'requirements' => entries }
+      end
+
+      def print_report(report)
+        entries = report['requirements']
+        if entries.empty?
+          puts 'No requirements to analyze.'
+          return
+        end
+
+        if entries.length == 1
+          print_detail(entries.first)
+          return
+        end
+
+        puts "Analysis triage — #{entries.length} requirement(s). Nothing was proposed or changed."
+        puts
+
+        ORDER.each do |action|
+          group = entries.select { |e| e['action'] == action }
+          next if group.empty?
+
+          puts "#{action.tr('_', ' ').upcase} (#{group.length}) — #{ACTIONS[action]}"
+          next if action == 'ok'
+
+          group.each { |e| print_line(e) }
+          puts
+        end
+        puts
+        puts 'Report first; file only the proposals a human picks. Each proposal moves its requirement to draft.'
+      end
+
+      def print_line(entry)
+        puts "  #{entry['slug']} — #{truncate(entry['title'].to_s, 70)}"
+        puts "    superseded by: #{entry['duplicate_of']}" if entry['duplicate_of']
+        entry['conflicts'].each do |c|
+          puts "    conflicts with #{c['slug']} (#{(c['probability'].to_f * 100).round}%)"
+        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?
+        puts "    error: #{entry['error']}" if entry['error']
+      end
+
+      def print_detail(entry)
+        puts "#{entry['slug']} — #{entry['title']}"
+        puts "  verdict: #{entry['verdict'] || '(none)'}   suggested: #{ACTIONS[entry['action']]}"
+        puts "  superseded by: #{entry['duplicate_of']}" if entry['duplicate_of']
+        puts "  fails: #{entry['failed_checks'].join(', ')}" unless entry['failed_checks'].empty?
+        entry['issues'].each { |i| puts "  issue: #{i['type']}" }
+        entry['conflicts'].each do |c|
+          puts "  conflict with #{c['slug']} (#{(c['probability'].to_f * 100).round}%): #{c['reason']}"
+        end
+        entry['suggestions'].each { |s| puts "  - #{s}" }
+        puts "  error: #{entry['error']}" if entry['error']
+      end
+
+      def progress(message)
+        warn message unless output.json?
+      end
+    end
+  end
+end