featureparity 0.0.5 → 0.0.7

data/lib/fp/commands/matrix.rb

@@ -2,75 +2,115 @@
 
 module Fp
   module Commands
-    # fp matrix --project <slug> [--csv]
-    # Show the requirements traceability matrix
+    # fp matrix [--project X] [--surface api] [--level covered] [--csv]
+    #
+    # The parity matrix: active requirements down the side, surfaces across the top,
+    # each cell showing the state of the evidence filed for that pair.
+    #
+    # This used to be computed here from `required_surfaces` alone and never read
+    # Evidence at all — every required cell rendered as "no evidence yet" and the legend
+    # advertised a ✅ the code could not produce. The grid now comes from the API's
+    # parity report, which is the same computation the CI gate blocks on, so what you
+    # see here is what CI will decide.
     class Matrix < Base
       KNOWN_FLAGS = {
         project: :string,
+        surface: :string,
+        level: :string,
         csv: :boolean
       }.freeze
 
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
-        require_flag(opts, :project)
+        project_config = ProjectConfig.discover
+        project_slug = require_project!(opts, project_config)
+        project_id = resolve_project_id(project_slug)
 
-        project_id = resolve_project_id(opts[:project])
-
-        # Get surfaces for the project
-        surfaces_result = client.list_surfaces(project_id)
-        unless surfaces_result[:ok]
-          output.error(surfaces_result[:error], status: surfaces_result[:status])
-          exit 1
-        end
-
-        surfaces = (surfaces_result[:data]['surfaces'] || []).map { |s| s['key'] }
-
-        # Get active requirements
-        req_result = client.list_requirements(project_id: project_id)
-        unless req_result[:ok]
-          output.error(req_result[:error], status: req_result[:status])
+        result = client.get_parity(
+          project_id,
+          level: opts[:level] || project_config.enforcement,
+          surface: opts[:surface] || project_config.surface
+        )
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
           exit 1
         end
 
-        requirements = (req_result[:data]['requirements'] || []).select { |r| r['status'] == 'active' }
+        report = result[:data]['parity'] || {}
+        surfaces = report['surfaces'] || []
+        requirements = report['requirements'] || []
 
         if requirements.empty?
-          output.success({ matrix: [], surfaces: surfaces }) do
+          output.success(report.merge('project' => project_slug)) do
             puts 'No active requirements. The matrix is empty.'
+            puts "Surfaces: #{surfaces.join(', ')}" unless surfaces.empty?
           end
           return
         end
 
-        # Build matrix data
-        # Columns: SLUG, TITLE, then one column per surface
         headers = %w[SLUG TITLE] + surfaces
 
-        rows = requirements.map do |req|
-          required = req['required_surfaces'] || []
-          # Evidence status per surface (placeholder until Evidence API exists)
-          surface_cells = surfaces.map do |s|
-            if required.include?(s)
-              '⬜'  # Required but no evidence yet
-            else
-              '-'   # Not required
-            end
-          end
-          [req['slug'], truncate(req['title'], 30)] + surface_cells
-        end
-
         if opts[:csv]
-          output.csv(headers, rows)
+          # CSV consumers want the state name, not a glyph they'd have to decode.
+          output.csv(headers, requirements.map { |req| build_row(req, surfaces, glyphs: false) })
         else
-          output.success({ requirements: requirements, surfaces: surfaces, project: opts[:project] }) do
-            puts "Parity Matrix: #{opts[:project]}"
-            puts
-            output.table(headers, rows)
-            puts
-            puts 'Legend: ✅ = passing, ⬜ = required (no evidence), - = not required'
+          rows = requirements.map { |req| build_row(req, surfaces) }
+          render_table(report, project_slug, headers, rows)
+        end
+      end
+
+      private
+
+      def build_row(requirement, surfaces, glyphs: true)
+        by_surface = (requirement['cells'] || []).to_h { |cell| [cell['surface'], cell['state']] }
+
+        cells = surfaces.map do |key|
+          state = by_surface[key]
+          if state.nil?
+            glyphs ? Parity::NOT_REQUIRED : 'not_required'
+          else
+            glyphs ? Parity.glyph(state) : state
           end
         end
+
+        [slug_cell(requirement, glyphs: glyphs), truncate(requirement['title'], 30)] + cells
+      end
+
+      # A requirement awaiting review of a proposed change is still measured, so it must
+      # still appear — but it reads as an ordinary row unless we say so, and its evidence
+      # has just been marked suspect. CSV gets a column-safe suffix rather than a glyph.
+      def slug_cell(requirement, glyphs: true)
+        return requirement['slug'] unless Parity.row_marker(requirement)
+
+        glyphs ? "#{requirement['slug']} #{Parity::UNDER_REVIEW}" : "#{requirement['slug']} (under review)"
       end
 
+      def render_table(report, project_slug, headers, rows)
+        output.success(report.merge('project' => project_slug)) do
+          scope = report['surface'] ? " (surface: #{report['surface']})" : ''
+          puts "Parity Matrix: #{project_slug}#{scope}"
+          puts
+          output.table(headers, rows)
+          puts
+          legend = Parity::LEGEND
+          pending = report['pending_reviews'] || []
+          legend += "  #{Parity::UNDER_REVIEW_LEGEND}" unless pending.empty?
+          puts legend
+
+          summary = report['summary'] || {}
+          counts = Parity.count_labels(summary)
+          puts counts.join('   ') unless counts.empty?
+
+          unless pending.empty?
+            puts "#{pending.size} awaiting review (#{Parity.pending_summary(pending)}) — fp history <slug>"
+          end
+
+          # The matrix is a report, not a gate — but say which way the gate would go, so
+          # nobody has to run `fp check` separately to find out.
+          verdict = report['passing'] ? 'passing' : "FAILING (#{summary['violations']} violation(s))"
+          puts "Gate at level '#{report['level']}': #{verdict}"
+        end
+      end
     end
   end
 end

data/lib/fp/commands/propose.rb

@@ -25,7 +25,7 @@ module Fp
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
 
-        require_flag(opts, :project)
+        require_project!(opts)
         require_flag(opts, :slug, '--slug is required (immutable identifier for the requirement)')
         require_flag(opts, :name, '--name is required (human-readable title)')
 

data/lib/fp/commands/propose_change.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Fp
+  module Commands
+    # `fp propose-change <slug>` — propose a modification to an existing requirement, or
+    # propose deleting it with --removal.
+    #
+    # Distinct from `fp propose`, which creates a brand new requirement. This one asks to
+    # change one that already exists, and the API records what it was, what is being
+    # asked for, and what prompted the ask. The requirement drops back to draft until a
+    # human reviews the diff — agents never approve their own changes.
+    class ProposeChange < Base
+      KNOWN_FLAGS = {
+        project: :string, name: :string, why: :string, acceptance: :string,
+        required: :string, category: :string, parent: :string, slug: :string,
+        reason: :string, source_type: :string, source_url: :string, source_context: :string,
+        removal: :boolean
+      }.freeze
+
+      VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
+      VALID_SOURCE_TYPES = %w[fizzy discord github_issue jira notion manual ai_chat].freeze
+
+      # Flags that describe a proposed new value, mapped to their API field.
+      FIELD_FLAGS = {
+        name: :title,
+        why: :why,
+        acceptance: :acceptance,
+        category: :category,
+        slug: :slug
+      }.freeze
+
+      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 propose-change <slug> [--project <project>] [flags]')
+          exit 1
+        end
+
+        validate_enums!(opts)
+
+        project_id = resolve_project_id(opts[:project])
+        requirement = find_requirement!(project_id, slug)
+
+        params = build_params(opts, project_id)
+        removal = opts[:removal] ? true : false
+
+        if !removal && params.keys.none? { |k| proposed_field?(k) }
+          output.error('Nothing to propose. Pass at least one of --name/--why/--acceptance/' \
+                       '--required/--category/--parent, or --removal to propose deletion.')
+          exit 1
+        end
+
+        result = client.propose_requirement_change(requirement['id'], params)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        print_result(result[:data], slug: slug, removal: removal)
+      end
+
+      private
+
+      def validate_enums!(opts)
+        if opts[:category] && !VALID_CATEGORIES.include?(opts[:category])
+          output.error("Invalid category '#{opts[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}")
+          exit 1
+        end
+
+        return unless opts[:source_type] && !VALID_SOURCE_TYPES.include?(opts[:source_type])
+
+        output.error("Invalid source type '#{opts[:source_type]}'. Must be one of: #{VALID_SOURCE_TYPES.join(', ')}")
+        exit 1
+      end
+
+      def find_requirement!(project_id, slug)
+        result = client.find_requirement_by_slug(project_id, slug)
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+        result[:data]['requirement']
+      end
+
+      def build_params(opts, project_id)
+        params = {}
+
+        FIELD_FLAGS.each { |flag, field| params[field] = opts[flag] if opts[flag] }
+        params[:required_surfaces] = opts[:required].split(',').map(&:strip) if opts[:required]
+        params[:parent_id] = resolve_parent_id(project_id, opts[:parent]) if opts[:parent]
+
+        params[:removal] = true if opts[:removal]
+        params[:reason] = opts[:reason] if opts[:reason]
+        params[:source_type] = opts[:source_type] if opts[:source_type]
+        params[:source_url] = opts[:source_url] if opts[:source_url]
+        params[:source_context] = opts[:source_context] if opts[:source_context]
+
+        params
+      end
+
+      def proposed_field?(key)
+        %i[title why acceptance category slug required_surfaces parent_id].include?(key)
+      end
+
+      def resolve_parent_id(project_id, parent_slug)
+        result = client.list_requirements(project_id: project_id)
+        unless result[:ok]
+          output.error("Failed to resolve parent slug '#{parent_slug}': #{result[:error]}")
+          exit 1
+        end
+
+        parent = (result[:data]['requirements'] || []).find { |r| r['slug'] == parent_slug }
+        unless parent
+          output.error("Parent requirement '#{parent_slug}' not found in this project")
+          exit 1
+        end
+
+        parent['id']
+      end
+
+      def print_result(data, slug:, removal:)
+        change = data['change'] || {}
+        requirement = data['requirement'] || {}
+
+        output.success(data) do
+          if removal
+            puts "Proposed DELETING requirement '#{slug}'."
+          else
+            puts "Proposed a change to requirement '#{slug}'."
+          end
+          puts
+
+          print_diff(change['changes'])
+          print_source(change)
+
+          puts "  Status:   #{requirement['status']}"
+          puts "  Change:   #{change['id']}"
+          puts
+          puts '⚠️  This requirement is back in DRAFT pending human review.'
+          puts "   Run `fp history #{slug} --project <project>` to see the full diff."
+          puts '   A human must approve or reject it in the web app. Agents cannot review changes.'
+        end
+      end
+
+      def print_diff(changes)
+        return if changes.nil? || changes.empty?
+
+        puts 'Proposed changes:'
+        changes.each do |field, change|
+          puts "  #{field}:"
+          puts "    - #{format_value(change['from'])}"
+          puts "    + #{format_value(change['to'])}"
+        end
+        puts
+      end
+
+      def print_source(change)
+        source = change['source'] || {}
+        return if source.empty? && change['reason'].nil?
+
+        puts 'Prompted by:'
+        puts "  Reason:  #{change['reason']}" if change['reason']
+        puts "  Source:  #{source['type']}" if source['type']
+        puts "  URL:     #{source['url']}" if source['url']
+        puts "  Context: #{source['context']}" if source['context']
+        puts
+      end
+
+      def format_value(value)
+        case value
+        when nil then '(none)'
+        when Array then value.empty? ? '(none)' : value.join(', ')
+        else value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/fp/commands/report.rb

@@ -19,6 +19,7 @@ module Fp
         project: :string,
         surface: :string,
         file: :string,
+        line: :string,
         repo: :string,
         pr: :string,
         sha: :string,
@@ -43,7 +44,7 @@ module Fp
           exit 1
         end
 
-        require_flag(opts, :project)
+        require_project!(opts)
         require_flag(opts, :surface)
         require_flag(opts, :file)
         require_flag(opts, :repo)
@@ -79,6 +80,7 @@ module Fp
         params[:work_item_url] = opts[:work_item] if opts[:work_item]
         params[:ci_url] = opts[:ci_url] if opts[:ci_url]
         params[:title] = opts[:title] if opts[:title]
+        params[:line] = opts[:line] if opts[:line]
 
         # Try to report evidence
         result = client.report_evidence(params)
@@ -89,7 +91,7 @@ module Fp
           output.success(params, summary: nil) do
             puts "Evidence for '#{slug}' on surface '#{opts[:surface]}':"
             puts "  State:     #{state}"
-            puts "  File:      #{opts[:file]}"
+            puts "  File:      #{opts[:file]}#{opts[:line] ? ":#{opts[:line]}" : ''}"
             puts "  Repo:      #{opts[:repo]}"
             puts "  PR:        #{opts[:pr]}" if opts[:pr]
             puts "  SHA:       #{opts[:sha]}" if opts[:sha]
@@ -110,7 +112,7 @@ module Fp
         output.success(result[:data]) do
           puts "Evidence reported for '#{slug}' on surface '#{opts[:surface]}'."
           puts "  State: #{state}"
-          puts "  File:  #{opts[:file]}"
+          puts "  File:  #{opts[:file]}#{opts[:line] ? ":#{opts[:line]}" : ''}"
           if opts[:pr]
             puts "  PR:    #{opts[:pr]}"
           end
@@ -130,7 +132,7 @@ module Fp
 
       # Batch-upload evidence from a JUnit XML report.
       def run_junit(opts)
-        require_flag(opts, :project)
+        require_project!(opts)
         require_flag(opts, :repo)
         # --surface is the default for markers that don't pin their own surface
         # (e.g. `fp:slug@api,web`). It's only strictly required when at least one
@@ -202,6 +204,7 @@ module Fp
             repo: opts[:repo],
             state: state
           }
+          params[:line] = binding.line if binding.line
           params[:pr_url] = opts[:pr] if opts[:pr]
           params[:sha] = opts[:sha] if opts[:sha]
           params[:work_item_url] = opts[:work_item] if opts[:work_item]
@@ -232,7 +235,7 @@ module Fp
       def emit_junit_summary(opts, reported, skipped_unknown, unmatched, api_unavailable)
         data = {
           repo: opts[:repo],
-          reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, file: r[:binding].file, state: r[:state], recorded: r[:recorded] } },
+          reported: reported.map { |r| { slug: r[:binding].slug, surface: r[:binding].surface, file: r[:binding].file, line: r[:binding].line, state: r[:state], recorded: r[:recorded] } },
           skipped_unknown: skipped_unknown.map { |b| { slug: b.slug, surface: b.surface, file: b.file } },
           unmatched_testcases: unmatched.map { |tc| { name: tc.name, file: tc.file } }
         }
@@ -241,7 +244,8 @@ module Fp
           puts "Reported evidence from #{opts[:junit]}:"
           reported.each do |r|
             marker = r[:recorded] ? '✓' : '•'
-            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}  (#{r[:state]})  #{r[:binding].file}"
+            loc = r[:binding].line ? "#{r[:binding].file}:#{r[:binding].line}" : r[:binding].file
+            puts "  #{marker} #{r[:binding].slug} → #{r[:binding].surface}  (#{r[:state]})  #{loc}"
           end
 
           unless skipped_unknown.empty?

data/lib/fp/commands/repos.rb

@@ -37,7 +37,7 @@ module Fp
 
       def set_repo(args)
         opts, positional = parse_flags(args, KNOWN_FLAGS)
-        require_flag(opts, :project)
+        require_project!(opts)
 
         surface = positional[0]
         path = positional[1]
@@ -65,7 +65,7 @@ module Fp
 
       def get_repo(args)
         opts, positional = parse_flags(args, KNOWN_FLAGS)
-        require_flag(opts, :project)
+        require_project!(opts)
 
         surface = positional[0]
         unless surface
@@ -123,7 +123,7 @@ module Fp
 
       def unset_repo(args)
         opts, positional = parse_flags(args, KNOWN_FLAGS)
-        require_flag(opts, :project)
+        require_project!(opts)
 
         surface = positional[0]
         unless surface

data/lib/fp/commands/show.rb

@@ -7,7 +7,7 @@ module Fp
     class Show < Base
       def run(args)
         opts, positional = parse_flags(args)
-        require_flag(opts, :project)
+        require_project!(opts)
 
         slug = positional.first
         unless slug
@@ -105,7 +105,10 @@ module Fp
               puts "  #{surface}:"
               records.each do |e|
                 puts "    Status:  #{e['status']}"
-                puts "    File:    #{e['source_file']}" if e['source_file']
+                if e['source_file']
+                  loc = e['source_line'] ? "#{e['source_file']}:#{e['source_line']}" : e['source_file']
+                  puts "    File:    #{loc}"
+                end
                 puts "    Repo:    #{e['repo']}" if e['repo']
                 puts "    PR:      #{e['pr_url']}" if e['pr_url']
                 puts "    Work:    #{e['work_item_url']}" if e['work_item_url']

data/lib/fp/commands/surfaces.rb

@@ -35,7 +35,7 @@ module Fp
 
       def list(args)
         opts, = parse_flags(args)
-        require_flag(opts, :project)
+        require_project!(opts)
 
         project_id = resolve_project_id(opts[:project])
         result = client.list_surfaces(project_id)
@@ -61,7 +61,7 @@ module Fp
 
       def add(args)
         opts, positional = parse_flags(args, ADD_FLAGS)
-        require_flag(opts, :project)
+        require_project!(opts)
 
         key = positional.first
         if key.nil? || key.strip.empty?

data/lib/fp/commands.rb

@@ -6,8 +6,14 @@ require_relative 'commands/surfaces'
 require_relative 'commands/list'
 require_relative 'commands/show'
 require_relative 'commands/propose'
+require_relative 'commands/propose_change'
+require_relative 'commands/history'
 require_relative 'commands/report'
+require_relative 'commands/ci_report'
+require_relative 'commands/check'
+require_relative 'commands/init'
 require_relative 'commands/matrix'
+require_relative 'commands/export'
 require_relative 'commands/profile'
 require_relative 'commands/config_cmd'
 require_relative 'commands/repos'

data/lib/fp/junit.rb

@@ -21,7 +21,11 @@ module Fp
     end
 
     # Evidence discovered by binding a testcase to a marker.
-    Binding = Struct.new(:slug, :surface, :file, :title, :state, keyword_init: true)
+    # `line` is the 1-based line number of the test in its source file: the
+    # testcase's own line when the runner reported one, otherwise the line of
+    # the fp:<slug> marker that annotates it (markers sit directly above the
+    # test, so the marker line is a close stand-in when the runner omits lines).
+    Binding = Struct.new(:slug, :surface, :file, :line, :title, :state, keyword_init: true)
 
     # Matches `fp:<slug>` inside a comment, with an optional `@surface` (or
     # `@surface1,surface2`) suffix to target one or more specific surfaces:
@@ -166,7 +170,7 @@ module Fp
             if surface.nil? || surface.empty?
               missing_surface << { slug: marker[:slug], file: tc.file }
             else
-              record_binding(bindings, marker[:slug], surface, tc, titles_reliable: titles_reliable)
+              record_binding(bindings, marker[:slug], surface, tc, marker, titles_reliable: titles_reliable)
             end
           end
         end
@@ -203,16 +207,21 @@ module Fp
       candidate
     end
 
-    def record_binding(bindings, slug, surface, testcase, titles_reliable: true)
+    def record_binding(bindings, slug, surface, testcase, marker, titles_reliable: true)
       rel_file = testcase.file
       key = [slug, surface, rel_file]
       state = testcase.stub? ? 'stub' : 'present'
 
+      # The test's line: prefer the runner-reported testcase line; fall back to
+      # the marker's line (it sits directly above the test) when the runner
+      # omitted line info.
+      line = testcase.line || (marker && marker[:line])
+
       existing = bindings[key]
       # Prefer a concrete 'present' state over 'stub' when a slug has both.
       return if existing && !(existing.state == 'stub' && state == 'present')
 
-      bindings[key] = Binding.new(slug: slug, surface: surface, file: rel_file,
+      bindings[key] = Binding.new(slug: slug, surface: surface, file: rel_file, line: line,
                                   title: (testcase.name if titles_reliable), state: state)
     end
 

data/lib/fp/parity.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Fp
+  # Presentation vocabulary for the parity grid.
+  #
+  # These are the cell states the API's parity report can return, with the glyph and
+  # ordering used to render them. This list is a copy of the server's
+  # ParityReport::STATE_SEVERITY keys, which is unavoidable across the gem/API boundary
+  # — but it is only ever used for *display*: which glyph to draw, and what order to
+  # list counts in.
+  #
+  # The CLI deliberately does not decide what a violation is. The server returns
+  # `violations` and `passing` already computed, and `fp check` exits on those. If it
+  # decided locally, every repo would enforce whichever gem version its CI installed,
+  # and raising a project's level would silently do nothing until every consumer
+  # upgraded. So an unknown state arriving from a newer API degrades to a bare glyph
+  # here rather than changing any verdict.
+  module Parity
+    # Worst → best, matching the server's severity order. Used for stable output.
+    STATES = %w[failing missing suspect stub present passing].freeze
+
+    GLYPHS = {
+      'passing' => '✓',
+      'failing' => '✗',
+      'present' => '●',
+      'stub' => '○',
+      'suspect' => '⚠',
+      'missing' => '·'
+    }.freeze
+
+    # Drawn for a surface a requirement does not require — not a state, an absence.
+    NOT_REQUIRED = '-'
+
+    # Marks a requirement whose proposed change is awaiting human review. Not a cell
+    # state: the requirement is still measured, and its cells still say what the evidence
+    # says. It's a row-level annotation so a reader can tell "uncovered" from "covered,
+    # but the wording just moved under the tests".
+    UNDER_REVIEW = '✎'
+
+    # Fallback for a state this gem version doesn't know about.
+    UNKNOWN_GLYPH = '?'
+
+    LEVELS = %w[off regression covered strict].freeze
+
+    LEGEND = 'Legend: ✓ passing  ✗ failing  ● present  ○ stub  ⚠ suspect  · missing  - not required'
+
+    # Appended to the legend only when the grid actually contains one, so the common
+    # case isn't cluttered by vocabulary nothing on screen uses.
+    UNDER_REVIEW_LEGEND = "#{UNDER_REVIEW} awaiting review of a proposed change"
+
+    def self.glyph(state)
+      GLYPHS.fetch(state.to_s, UNKNOWN_GLYPH)
+    end
+
+    # Row-level annotation for a requirement, or nil when there's nothing to say.
+    def self.row_marker(row)
+      UNDER_REVIEW if row['under_review'] || row[:under_review]
+    end
+
+    # "2 modifications, 1 deletion" for a pending_reviews list.
+    def self.pending_summary(pending_reviews)
+      kinds = Array(pending_reviews).map { |p| p['kind'] || p[:kind] }
+      removals = kinds.count('removal')
+      modifications = kinds.size - removals
+
+      parts = []
+      parts << "#{modifications} modification#{'s' unless modifications == 1}" if modifications.positive?
+      parts << "#{removals} deletion#{'s' unless removals == 1}" if removals.positive?
+      parts.join(', ')
+    end
+
+    # State counts in severity order, skipping zeros, as "✗ 2 failing" strings.
+    def self.count_labels(summary)
+      STATES.filter_map do |state|
+        count = summary[state].to_i
+        "#{glyph(state)} #{count} #{state}" if count.positive?
+      end
+    end
+  end
+end