featureparity 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b5b8ef2f8e259e3d8d7ecd0c547ad8bef6f6202e0b3564bd8d789de905661ed
-  data.tar.gz: 79d02f1bfdd3c95b1d94a40b2cda406d656c4970a0c6b3f60b792415b4417c62
+  metadata.gz: 1208887c7ed99691e476438cdcb50d36f09e3ee3b22931c7d8d9ea246438fb89
+  data.tar.gz: b2fb9b9d7bad99bde7e2f8b0789105072cd19647ed46f0ea4d4d6e43a28fd319
 SHA512:
-  metadata.gz: e737b8e544deaa42e6ada2f6af065c5afdeaa46afa51d5365c5f8a92fa77572e1f5c1a13715a11eb0655416a08e487f4b8e9bb7f7ffa9efc3a6042abcc1c45ad
-  data.tar.gz: 247e22500f20fcd047a617232020f29a87987ac2376a78176a69969a467b8d8164b4dd6a427c73c558965b7aa9543ffb2e0b659416974ec5272f76d2618c415e
+  metadata.gz: 5d70c2ae5afb585a1f54da0c2efb244965a0f419001c9ed8f46d1895a5f37ee12ece8a1195627859eeeaff2fd3910cf4dfdb593fc41c69440bc97020ff31a17a
+  data.tar.gz: 23d9038f6850138f295501a56ea00f872ff828eab5a2822482c306a56ba39cdec2a1016761af8f4f87932a3d9f264faf0c9dad3302d2a96ea5adceb86b3e29c6

data/lib/fp/client.rb

@@ -27,6 +27,11 @@ module Fp
       get("/api/projects/#{project_id}/surfaces")
     end
 
+    # POST /projects/:id/surfaces
+    def create_surface(project_id, params)
+      post("/api/projects/#{project_id}/surfaces", params)
+    end
+
     # GET /requirements
     def list_requirements(project_id: nil, status: nil, category: nil)
       params = {}
@@ -67,6 +72,15 @@ module Fp
       put("/api/requirements/#{id}", 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)
+      params = {}
+      params[:slug] = slug if slug
+      params[:surface] = surface if surface
+      get("/api/projects/#{project_id}/evidence", params)
+    end
+
     # POST /projects/:project_id/evidence (direct reporting)
     def report_evidence(params)
       project_id = params.delete(:project_id)

data/lib/fp/commands/help.rb

@@ -14,6 +14,7 @@ module Fp
           COMMANDS
             projects                          List projects you have access to
             surfaces --project <slug>         List surfaces for a project
+            surfaces add <key> --project ...  Create a surface
             list --project <slug>             List active requirements
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
@@ -68,6 +69,15 @@ module Fp
             # List projects
             fp projects
 
+            # List the surfaces a project tracks (requirements may only name these)
+            fp surfaces --project stowzilla
+
+            # Create a surface (agents can do this — no need to wait on the web app)
+            fp surfaces add customer_android --project stowzilla \\
+              --name "Customer Android App" \\
+              --kind android \\
+              --repo stowzilla/customer-android
+
             # List requirements for a project
             fp list --project stowzilla
 
@@ -89,6 +99,14 @@ module Fp
               --acceptance "QR code is printed and scannable" \\
               --category functional
 
+            # Nest a requirement under a parent (--parent takes the parent's SLUG).
+            # A child's --required surfaces must be a subset of its parent's.
+            fp propose --project stowzilla \\
+              --slug print_container_qr_ios \\
+              --name "Print QR on iOS" \\
+              --parent print_container_qr \\
+              --required customer_ios
+
             # Report evidence for a requirement
             fp report print_container_qr --project stowzilla \\
               --surface customer_android \\

data/lib/fp/commands/propose.rb

@@ -13,10 +13,14 @@ module Fp
         required: :string,
         acceptance: :string,
         parent: :string,
-        category: :string
+        category: :string,
+        source_type: :string,
+        source_url: :string,
+        source_context: :string
       }.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
 
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
@@ -31,6 +35,11 @@ module Fp
           exit 1
         end
 
+        if 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
+
         project_id = resolve_project_id(opts[:project])
 
         # Parse required surfaces (comma-separated)
@@ -49,6 +58,9 @@ module Fp
         params[:why] = opts[:why] if opts[:why]
         params[:acceptance] = opts[:acceptance] if opts[:acceptance]
         params[:category] = opts[:category] if opts[:category]
+        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]
 
         # Resolve parent slug to parent_id if provided
         if opts[:parent]

data/lib/fp/commands/show.rb

@@ -25,21 +25,49 @@ module Fp
 
         requirement = result[:data]['requirement']
 
-        output.success(result[:data]) do
-          print_requirement(requirement)
+        # Evidence is not embedded in the requirement payload — it lives on the project's
+        # evidence collection, keyed by slug. Fetch it, or `fp show` reports "(none)" for
+        # every requirement no matter how many receipts have been filed.
+        evidence = fetch_evidence(project_id, slug)
+
+        # Agents only ever speak slugs, so translate the parent's ID back into one.
+        parent_slug = resolve_parent_slug(project_id, requirement['parent_id'])
+
+        payload = result[:data].merge('evidence' => evidence)
+        payload['parent_slug'] = parent_slug if parent_slug
+
+        output.success(payload) do
+          print_requirement(requirement, evidence: evidence, parent_slug: parent_slug)
         end
       end
 
       private
 
-      def print_requirement(req)
+      def fetch_evidence(project_id, slug)
+        result = client.list_evidence(project_id, slug: slug)
+        return [] unless result[:ok]
+
+        result[:data]['evidence'] || []
+      end
+
+      def resolve_parent_slug(project_id, parent_id)
+        return nil if parent_id.nil? || parent_id.to_s.empty?
+
+        result = client.list_requirements(project_id: project_id)
+        return nil unless result[:ok]
+
+        parent = (result[:data]['requirements'] || []).find { |r| r['id'] == parent_id }
+        parent && parent['slug']
+      end
+
+      def print_requirement(req, evidence: [], parent_slug: nil)
         puts "#{req['title']}"
         puts "=" * req['title'].length
         puts
         puts "Slug:     #{req['slug']}"
         puts "Status:   #{req['status']}"
         puts "Category: #{req['category'] || '(none)'}"
-        puts "Parent:   #{req['parent_id'] || '(none)'}"
+        puts "Parent:   #{parent_slug || req['parent_id'] || '(none)'}"
         puts
 
         surfaces = req['required_surfaces'] || []
@@ -63,26 +91,31 @@ module Fp
           puts
         end
 
-        # Evidence receipts (will be populated when Evidence model exists)
-        evidence = req['evidence'] || []
-        if evidence.any?
-          puts 'Evidence:'
-          evidence.each do |e|
-            puts "  #{e['surface']}:"
-            puts "    Status:  #{e['status']}"
-            puts "    File:    #{e['file']}" if e['file']
-            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']
-            puts "    CI:      #{e['ci_url']}" if e['ci_url']
-            puts "    Title:   #{e['example_title']}" if e['example_title']
-            puts "    By:      #{e['reported_by']}" if e['reported_by']
-            puts
-          end
-        else
-          puts 'Evidence:'
+        # Evidence receipts, newest first, grouped per surface.
+        puts 'Evidence:'
+        if evidence.empty?
           puts '  (none reported)'
           puts
+        else
+          evidence
+            .sort_by { |e| e['reported_at'].to_s }
+            .reverse
+            .group_by { |e| e['surface'] }
+            .each do |surface, records|
+              puts "  #{surface}:"
+              records.each do |e|
+                puts "    Status:  #{e['status']}"
+                puts "    File:    #{e['source_file']}" if e['source_file']
+                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']
+                puts "    CI:      #{e['ci_url']}" if e['ci_url']
+                puts "    Title:   #{e['example_title']}" if e['example_title']
+                puts "    By:      #{e['source']}" if e['source']
+                puts "    At:      #{e['reported_at']}" if e['reported_at']
+                puts
+              end
+            end
         end
 
         puts "Created:  #{req['created_at']}"

data/lib/fp/commands/surfaces.rb

@@ -2,9 +2,38 @@
 
 module Fp
   module Commands
-    # fp surfaces --project <slug> - list available surfaces for a project
+    # fp surfaces --project <slug>              - list available surfaces for a project
+    # fp surfaces add <key> --project <slug>    - create a surface
+    #
+    # `add` exists because a requirement can only name surfaces that already exist, so an
+    # agent onboarding a project it hasn't seen before would otherwise be blocked waiting
+    # on a human to click through the web app.
     class Surfaces < Base
+      ADD_FLAGS = {
+        project: :string,
+        name: :string,
+        kind: :string,
+        audience: :string,
+        repo: :string,
+        default_branch: :string
+      }.freeze
+
+      VALID_KINDS = %w[api web android ios other].freeze
+      VALID_AUDIENCES = %w[customer ops both internal].freeze
+
       def run(args)
+        # Subcommand dispatch. Bare `fp surfaces --project X` stays a list, so existing
+        # callers (and the docs) keep working.
+        if args.first == 'add'
+          add(args[1..])
+        else
+          list(args)
+        end
+      end
+
+      private
+
+      def list(args)
         opts, = parse_flags(args)
         require_flag(opts, :project)
 
@@ -22,13 +51,63 @@ module Fp
         output.success({ surfaces: surfaces, project: opts[:project] }) do
           if surfaces.empty?
             puts "No surfaces configured for project '#{opts[:project]}'."
-            puts 'Configure surfaces in the web app.'
+            puts "Add one with: fp surfaces add <key> --project #{opts[:project]} --name \"<Name>\""
           else
             puts "Surfaces for '#{opts[:project]}':"
             surfaces.each { |s| puts "  - #{s}" }
           end
         end
       end
+
+      def add(args)
+        opts, positional = parse_flags(args, ADD_FLAGS)
+        require_flag(opts, :project)
+
+        key = positional.first
+        if key.nil? || key.strip.empty?
+          output.error('Usage: fp surfaces add <key> --project <slug> [--name "Name"] [--kind api|web|android|ios|other]')
+          exit 1
+        end
+
+        validate_choice!(opts[:kind], VALID_KINDS, '--kind')
+        validate_choice!(opts[:audience], VALID_AUDIENCES, '--audience')
+
+        project_id = resolve_project_id(opts[:project])
+
+        # The API derives key from name and defaults kind/audience/default_branch, but we
+        # send the key explicitly because here the key is what the caller actually typed —
+        # `add api --name "Backend API"` must produce `api`, not `backend_api`.
+        params = { key: key, name: opts[:name] || key }
+        params[:kind] = opts[:kind] if opts[:kind]
+        params[:audience] = opts[:audience] if opts[:audience]
+        params[:repo] = opts[:repo] if opts[:repo]
+        params[:default_branch] = opts[:default_branch] if opts[:default_branch]
+
+        result = client.create_surface(project_id, params)
+
+        unless result[:ok]
+          output.error(result[:error], status: result[:status])
+          exit 1
+        end
+
+        surface = result[:data]['surface'] || {}
+
+        output.success(result[:data]) do
+          puts "Created surface '#{surface['key'] || key}' in project '#{opts[:project]}'."
+          puts
+          puts "  Name:     #{surface['name']}"
+          puts "  Kind:     #{surface['kind']}"
+          puts "  Audience: #{surface['audience']}"
+          puts "  Repo:     #{surface['repo'] || '(none)'}"
+        end
+      end
+
+      def validate_choice!(value, allowed, flag)
+        return if value.nil? || allowed.include?(value)
+
+        output.error("Invalid #{flag} '#{value}'. Must be one of: #{allowed.join(', ')}")
+        exit 1
+      end
     end
   end
 end

data/lib/fp/junit.rb

@@ -34,6 +34,16 @@ module Fp
     # (matching the propose/report convention).
     MARKER_RE = /fp:([a-z0-9][a-z0-9_-]*)(?:@([a-z0-9_-]+(?:,[a-z0-9_-]+)*))?/.freeze
 
+    # A marker only counts when it is a comment on its own line — the documented
+    # convention ("the fp:<slug> comment sits immediately above its test"). Requiring a
+    # line-leading comment token is what keeps marker-shaped text inside string literals,
+    # fixtures and docs from being mistaken for a real annotation. Without it, any test
+    # suite that has tests *about* fp markers reports evidence for its own fixtures.
+    #
+    # Covers #, //, --, and both the opening and continuation lines of /* ... */ blocks,
+    # which spans every language the marker convention documents.
+    COMMENT_LINE_RE = %r{\A\s*(?:\#|//|--|/\*|\*)}.freeze
+
     module_function
 
     # Parse a JUnit XML file into an array of TestCase structs.
@@ -52,10 +62,14 @@ module Fp
       cases = []
 
       doc.each_element('//testcase') do |el|
+        parent = el.parent
+        suite_name = parent && parent.expanded_name == 'testsuite' ? parent.attributes['name'] : nil
+        classname = el.attributes['classname']
+
         cases << TestCase.new(
           name: el.attributes['name'],
-          classname: el.attributes['classname'],
-          file: el.attributes['file'],
+          classname: classname,
+          file: resolve_file(el.attributes['file'], classname, suite_name),
           line: (el.attributes['line'] && el.attributes['line'].to_i),
           status: testcase_status(el)
         )
@@ -64,6 +78,26 @@ module Fp
       cases
     end
 
+    # Runners disagree about where the source file goes. Minitest- and RSpec-style reports
+    # put it on the testcase's `file` attribute; vitest and jest omit `file` entirely and
+    # carry the path in `classname` and the enclosing `<testsuite name>`. Markers live in
+    # the file, so fall back through the alternatives instead of silently finding nothing.
+    def resolve_file(file, classname, suite_name)
+      return file if file && !file.empty?
+
+      [classname, suite_name].find { |candidate| path_like?(candidate) }
+    end
+
+    # Distinguish a source path from a bare test-class name. Deliberately conservative:
+    # a Java-style `com.example.FooTest` classname must not be mistaken for a file.
+    TEST_FILE_EXT_RE = /\.(rb|js|jsx|mjs|cjs|ts|tsx|kt|kts|swift|java|py|go|cs|php|rs|scala)\z/.freeze
+
+    def path_like?(value)
+      return false if value.nil? || value.empty?
+
+      value.include?('/') || value.match?(TEST_FILE_EXT_RE)
+    end
+
     # Determine present/skipped for a testcase element.
     # Failures/errors still count as "present" for agent evidence — the test
     # exists and was executed. Only skipped/pending tests become stubs.
@@ -113,6 +147,12 @@ module Fp
         markers = markers_for(cases.first, base_dir, marker_cache)
         next if markers.empty?
 
+        # A title is only trustworthy when we know which test the marker annotates: either
+        # the report carried line numbers, or the file holds a single test. Otherwise the
+        # marker was matched file-wide and naming any one test would be a guess — vitest
+        # and jest emit no line numbers, so this is the common case, not an edge one.
+        titles_reliable = cases.any?(&:line) || cases.length == 1
+
         cases.each do |tc|
           marker = marker_for(tc, cases, markers)
           next unless marker
@@ -126,7 +166,7 @@ module Fp
             if surface.nil? || surface.empty?
               missing_surface << { slug: marker[:slug], file: tc.file }
             else
-              record_binding(bindings, marker[:slug], surface, tc)
+              record_binding(bindings, marker[:slug], surface, tc, titles_reliable: titles_reliable)
             end
           end
         end
@@ -163,7 +203,7 @@ module Fp
       candidate
     end
 
-    def record_binding(bindings, slug, surface, testcase)
+    def record_binding(bindings, slug, surface, testcase, titles_reliable: true)
       rel_file = testcase.file
       key = [slug, surface, rel_file]
       state = testcase.stub? ? 'stub' : 'present'
@@ -173,7 +213,7 @@ module Fp
       return if existing && !(existing.state == 'stub' && state == 'present')
 
       bindings[key] = Binding.new(slug: slug, surface: surface, file: rel_file,
-                                  title: testcase.name, state: state)
+                                  title: (testcase.name if titles_reliable), state: state)
     end
 
     # Load and cache the fp:<slug> markers (with line numbers) for a testcase's
@@ -198,9 +238,13 @@ module Fp
     # Scan file contents for fp:<slug>[@surface[,surface...]] markers, returning
     # [{ slug:, surfaces: [..], line: }, ...] (1-based line numbers).
     # `surfaces` is [] when the marker pins none (use the default surface).
+    #
+    # Only comment lines are considered — see COMMENT_LINE_RE.
     def scan_markers(contents)
       markers = []
       contents.each_line.with_index(1) do |line, num|
+        next unless line.match?(COMMENT_LINE_RE)
+
         line.scan(MARKER_RE) do |(slug, surface_list)|
           surfaces = surface_list ? surface_list.split(',').map(&:strip).reject(&:empty?) : []
           markers << { slug: slug, surfaces: surfaces, line: num }

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Stowzilla
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-12 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http