featureparity 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fec4ef9bda94cba09b19e5209ed867ff87d6a5312c6c6441234691e406bd2a2
-  data.tar.gz: 7fd7a58df29f9a69ce342ed60e5b7ff60b796f286404b81a56108be1f5c83f1b
+  metadata.gz: 166fe16ad8636be840cc889d1104ad4e6a5f3c84cd046f0a94f291412083f344
+  data.tar.gz: e88add572a4cfd638768ae4d65de5a207b6a64c450ca0fdce426f48e8e51427e
 SHA512:
-  metadata.gz: b198114877fb8ca6695f14c38796334b2cf4269e4164509a97a7b0d12cf4fa7f86ecbd4036028fad15fb80eb00d95da5a410542eda6cdcbd7366b33e6c0dab11
-  data.tar.gz: 7a6a248d554a4fa13bc5b33591be0868f2714dfc483c81da0ceafaa4fa951f5f915c229ac8096fbda59efae8319c39e135e4b36e4403944c6ceec80cc7f74832
+  metadata.gz: c3d5bee44367c02c8329c10bdb3c0615978c405c30d46fb002b1ca7fe6676a61075dc83bf4ba02ba01faf828d80fa7f56af2116fd5287f662166bf547d9c5468
+  data.tar.gz: 5b627165e1205cca331626fd46b35d7ad71b9ed666fd63ebe96569b2e2989b4b14ff35426d099a1e7dfd8afe7ac16c7984e53ec1052262a374914505c950404c

data/lib/fp/cli.rb

@@ -13,6 +13,7 @@ module Fp
       'matrix' => Commands::Matrix,
       'profile' => Commands::Profile,
       'config' => Commands::ConfigCmd,
+      'repos' => Commands::Repos,
       'setup' => Commands::Setup,
       'version' => Commands::Version,
       'help' => Commands::Help
@@ -34,7 +35,7 @@ module Fp
         end
 
         # Profile/config commands don't need auth
-        needs_auth = !%w[profile config setup version help].include?(command_name)
+        needs_auth = !%w[profile config repos setup version help].include?(command_name)
 
         if needs_auth
           config = Config.new(profile: global_opts[:profile], api_url: global_opts[:api_url])

data/lib/fp/client.rb

@@ -12,21 +12,27 @@ module Fp
       @base_url = config.api_url.chomp('/')
     end
 
-    # GET /workspaces (called "projects" in the CLI)
+    # GET /projects
     def list_projects
-      get('/api/workspaces')
+      get('/api/projects')
     end
 
-    # GET /workspaces/:id
+    # GET /projects/:id
     def get_project(id)
-      get("/api/workspaces/#{id}")
+      get("/api/projects/#{id}")
+    end
+
+    # GET /projects/:id/surfaces
+    def list_surfaces(project_id)
+      get("/api/projects/#{project_id}/surfaces")
     end
 
     # GET /requirements
-    def list_requirements(workspace_id: nil, status: nil)
+    def list_requirements(project_id: nil, status: nil, category: nil)
       params = {}
-      params[:workspace_id] = workspace_id if workspace_id
+      params[:project_id] = project_id if project_id
       params[:status] = status if status
+      params[:category] = category if category
       get('/api/requirements', params)
     end
 
@@ -35,10 +41,10 @@ module Fp
       get("/api/requirements/#{id}")
     end
 
-    # GET /requirements by slug within a workspace
-    def find_requirement_by_slug(workspace_id, slug)
-      # List all requirements for the workspace and find by slug
-      result = list_requirements(workspace_id: workspace_id)
+    # GET /requirements by slug within a project
+    def find_requirement_by_slug(project_id, slug)
+      # List all requirements for the project and find by slug
+      result = list_requirements(project_id: project_id)
       return result unless result[:ok]
 
       requirements = result[:data]['requirements'] || []
@@ -47,7 +53,7 @@ module Fp
       if requirement
         { ok: true, data: { 'requirement' => requirement } }
       else
-        { ok: false, error: "Requirement '#{slug}' not found in workspace", status: 404 }
+        { ok: false, error: "Requirement '#{slug}' not found in project", status: 404 }
       end
     end
 
@@ -61,20 +67,21 @@ module Fp
       put("/api/requirements/#{id}", params)
     end
 
-    # POST /evidence (when API is ready)
+    # POST /projects/:project_id/evidence (direct reporting)
     def report_evidence(params)
-      post('/api/evidence', params)
+      project_id = params.delete(:project_id)
+      post("/api/projects/#{project_id}/evidence", params)
     end
 
     # GET /matrix (when API is ready)
-    def get_matrix(workspace_id, format: :json)
+    def get_matrix(project_id, format: :json)
       path = format == :csv ? '/api/matrix.csv' : '/api/matrix'
-      get(path, { workspace_id: workspace_id })
+      get(path, { project_id: project_id })
     end
 
     # GET /gaps (when API is ready)
-    def get_gaps(workspace_id, surface: nil)
-      params = { workspace_id: workspace_id }
+    def get_gaps(project_id, surface: nil)
+      params = { project_id: project_id }
       params[:surface] = surface if surface
       get('/api/gaps', params)
     end

data/lib/fp/commands/base.rb

@@ -50,26 +50,26 @@ module Fp
         [opts, positional]
       end
 
-      # Resolve workspace ID from --project flag (can be slug or ID)
-      def resolve_workspace_id(project_slug_or_id)
+      # Resolve project ID from --project flag (can be slug or ID)
+      def resolve_project_id(project_slug_or_id)
         return nil unless project_slug_or_id
 
-        # First try to find by listing workspaces
+        # First try to find by listing projects
         result = client.list_projects
         unless result[:ok]
           output.error(result[:error], status: result[:status])
           exit 1
         end
 
-        workspaces = result[:data]['workspaces'] || []
-        workspace = workspaces.find { |w| w['slug'] == project_slug_or_id || w['id'] == project_slug_or_id }
+        projects = result[:data]['projects'] || []
+        project = projects.find { |w| w['slug'] == project_slug_or_id || w['id'] == project_slug_or_id }
 
-        unless workspace
+        unless project
           output.error("Project '#{project_slug_or_id}' not found")
           exit 1
         end
 
-        workspace['id']
+        project['id']
       end
 
       def require_flag(opts, flag, message = nil)

data/lib/fp/commands/help.rb

@@ -18,9 +18,11 @@ module Fp
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
             report <slug> --project <slug>... Report evidence for a requirement
+            report --junit <file> ...         Upload evidence from a JUnit XML report (no CI)
             matrix --project <slug>           Show the parity matrix
             profile add|list                  Manage named profiles
             config set|get|unset|list         Manage global settings
+            repos set|get|list|unset          Map surfaces to local repo paths
             setup                             Interactive first-time setup
             version                           Show version
             help                              Show this help
@@ -63,6 +65,9 @@ module Fp
             # List requirements for a project
             fp list --project stowzilla
 
+            # List requirements filtered by category
+            fp list --project stowzilla --category security
+
             # Show gaps (requirements without evidence)
             fp list --project stowzilla --gaps --surface customer_android
 
@@ -75,7 +80,8 @@ module Fp
               --name "Print QR code on container label" \\
               --why "Customers scan to track containers" \\
               --required api,customer_android,customer_ios \\
-              --acceptance "QR code is printed and scannable"
+              --acceptance "QR code is printed and scannable" \\
+              --category functional
 
             # Report evidence for a requirement
             fp report print_container_qr --project stowzilla \\
@@ -86,12 +92,31 @@ module Fp
               --work-item https://app.fizzy.do/123/cards/456 \\
               --title "prints a QR code onto the container label"
 
+            # Upload evidence without CI: run your suite, emit JUnit XML, upload it.
+            # fp parses the report, finds the fp:<slug> markers in the test files,
+            # and reports evidence for every requirement the suite covered.
+            #   rspec --format RspecJunitFormatter --out junit.xml   # (or your runner's equivalent)
+            fp report --junit junit.xml --project stowzilla \\
+              --surface api \\
+              --repo stowzilla/marketplace \\
+              --work-item https://app.fizzy.do/123/cards/456
+            # --base-dir sets where relative test file paths in the report resolve from
+            # Skipped tests are reported as 'stub'; everything else as 'present'.
+
             # Show the parity matrix
             fp matrix --project stowzilla
 
             # Export matrix as CSV
             fp matrix --project stowzilla --csv > matrix.csv
 
+            # Map a surface to a local repo on this machine
+            fp repos set customer_android ~/code/customer-android \\
+              --project stowzilla --repo stowzilla/customer-android
+
+            # Find where a surface's code lives locally (for agents)
+            fp repos get customer_android --project stowzilla
+            cd "$(fp repos get customer_android --project stowzilla)"
+
           MARKER CONVENTION
             Tests are bound to requirements using the fp:<slug> marker in the test file.
             The CLI does not rewrite test files - you add the marker yourself.
@@ -115,6 +140,18 @@ module Fp
                 ...
               }
 
+            PINNING SURFACES IN THE MARKER
+              A marker may target one or more surfaces with an @suffix. This is
+              handy when a single (e.g. backend) test satisfies several surfaces:
+
+                # fp:print_container_qr            -> uses the --surface flag
+                # fp:print_container_qr@api        -> reports for the api surface
+                # fp:print_container_qr@api,web    -> reports for api AND web
+
+              With `fp report --junit`, each pinned surface produces its own
+              evidence upload. Markers without an @surface fall back to --surface;
+              if a marker pins none and no --surface is given, the run errors.
+
           MORE INFORMATION
             https://featureparity.dev/docs
         HELP

data/lib/fp/commands/list.rb

@@ -2,12 +2,13 @@
 
 module Fp
   module Commands
-    # fp list --project <slug> [--surface X] [--gaps] [--status draft]
+    # fp list --project <slug> [--surface X] [--category Y] [--gaps] [--status draft]
     # List requirements, optionally filtered
     class List < Base
       KNOWN_FLAGS = {
         project: :string,
         surface: :string,
+        category: :string,
         status: :string,
         gaps: :boolean
       }.freeze
@@ -16,19 +17,19 @@ module Fp
         opts, = parse_flags(args, KNOWN_FLAGS)
         require_flag(opts, :project)
 
-        workspace_id = resolve_workspace_id(opts[:project])
+        project_id = resolve_project_id(opts[:project])
 
         if opts[:gaps]
-          list_gaps(workspace_id, opts)
+          list_gaps(project_id, opts)
         else
-          list_requirements(workspace_id, opts)
+          list_requirements(project_id, opts)
         end
       end
 
       private
 
-      def list_requirements(workspace_id, opts)
-        result = client.list_requirements(workspace_id: workspace_id)
+      def list_requirements(project_id, opts)
+        result = client.list_requirements(project_id: project_id, category: opts[:category])
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
@@ -50,7 +51,10 @@ module Fp
 
         output.success({ requirements: requirements, project: opts[:project] }) do
           if requirements.empty?
-            puts "No #{status_filter} requirements found."
+            filter_desc = [status_filter]
+            filter_desc << "category: #{opts[:category]}" if opts[:category]
+            filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
+            puts "No requirements found (#{filter_desc.join(', ')})."
           else
             # Group into tree structure: parents first, then children indented
             parents = requirements.select { |r| r['parent_id'].nil? || r['parent_id'] == '' }
@@ -62,24 +66,27 @@ module Fp
             parent_ids = parents.map { |p| p['id'] }.to_set
             orphans = requirements.select { |r| r['parent_id'] && r['parent_id'] != '' && !parent_ids.include?(r['parent_id']) }
 
-            headers = %w[SLUG TITLE SURFACES STATUS]
+            headers = %w[SLUG TITLE CATEGORY SURFACES STATUS]
             rows = []
 
             parents.each do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
-              rows << [r['slug'], truncate(r['title'], 40), surfaces.empty? ? '-' : surfaces, r['status']]
+              category = r['category'] || '-'
+              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, r['status']]
 
               # Add children indented
               (children_by_parent[r['id']] || []).each do |child|
                 child_surfaces = (child['required_surfaces'] || []).join(', ')
-                rows << ["  └ #{child['slug']}", truncate(child['title'], 36), child_surfaces.empty? ? '-' : child_surfaces, child['status']]
+                child_category = child['category'] || '-'
+                rows << ["  └ #{child['slug']}", truncate(child['title'], 36), child_category, child_surfaces.empty? ? '-' : child_surfaces, child['status']]
               end
             end
 
             # Show orphans at top level
             orphans.each do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
-              rows << [r['slug'], truncate(r['title'], 40), surfaces.empty? ? '-' : surfaces, r['status']]
+              category = r['category'] || '-'
+              rows << [r['slug'], truncate(r['title'], 40), category, surfaces.empty? ? '-' : surfaces, r['status']]
             end
 
             output.table(headers, rows)
@@ -87,10 +94,10 @@ module Fp
         end
       end
 
-      def list_gaps(workspace_id, opts)
+      def list_gaps(project_id, opts)
         # Gaps endpoint may not exist yet - fall back to computing from requirements
         # For now, list requirements that don't have evidence for a surface
-        result = client.list_requirements(workspace_id: workspace_id)
+        result = client.list_requirements(project_id: project_id, category: opts[:category])
 
         unless result[:ok]
           output.error(result[:error], status: result[:status])
@@ -109,15 +116,24 @@ module Fp
 
         # For now, gaps = all requirements (evidence API is #1214)
         # Once evidence API exists, filter to only those without evidence
-        output.success({ gaps: requirements, project: opts[:project], surface: opts[:surface] }) do
+        output.success({ gaps: requirements, project: opts[:project], surface: opts[:surface], category: opts[:category] }) do
           if requirements.empty?
-            puts 'No gaps found.'
+            filter_desc = []
+            filter_desc << "category: #{opts[:category]}" if opts[:category]
+            filter_desc << "surface: #{opts[:surface]}" if opts[:surface]
+            msg = 'No gaps found'
+            msg += " (#{filter_desc.join(', ')})" unless filter_desc.empty?
+            puts "#{msg}."
           else
-            puts "Gaps for project '#{opts[:project]}'" + (opts[:surface] ? " (surface: #{opts[:surface]})" : '') + ':'
-            headers = %w[SLUG TITLE SURFACES]
+            desc = "Gaps for project '#{opts[:project]}'"
+            desc += " (surface: #{opts[:surface]})" if opts[:surface]
+            desc += " (category: #{opts[:category]})" if opts[:category]
+            puts "#{desc}:"
+            headers = %w[SLUG TITLE CATEGORY SURFACES]
             rows = requirements.map do |r|
               surfaces = (r['required_surfaces'] || []).join(', ')
-              [r['slug'], truncate(r['title'], 40), surfaces]
+              category = r['category'] || '-'
+              [r['slug'], truncate(r['title'], 40), category, surfaces]
             end
             output.table(headers, rows)
           end

data/lib/fp/commands/matrix.rb

@@ -14,20 +14,19 @@ module Fp
         opts, = parse_flags(args, KNOWN_FLAGS)
         require_flag(opts, :project)
 
-        workspace_id = resolve_workspace_id(opts[:project])
+        project_id = resolve_project_id(opts[:project])
 
-        # Get workspace for surfaces
-        ws_result = client.get_project(workspace_id)
-        unless ws_result[:ok]
-          output.error(ws_result[:error], status: ws_result[:status])
+        # 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
 
-        workspace = ws_result[:data]['workspace']
-        surfaces = workspace['available_surfaces'] || []
+        surfaces = (surfaces_result[:data]['surfaces'] || []).map { |s| s['key'] }
 
         # Get active requirements
-        req_result = client.list_requirements(workspace_id: workspace_id)
+        req_result = client.list_requirements(project_id: project_id)
         unless req_result[:ok]
           output.error(req_result[:error], status: req_result[:status])
           exit 1

data/lib/fp/commands/projects.rb

@@ -2,7 +2,7 @@
 
 module Fp
   module Commands
-    # fp projects - list projects/workspaces the API key has access to
+    # fp projects - list projects the API key has access to
     class Projects < Base
       def run(_args)
         result = client.list_projects
@@ -12,15 +12,21 @@ module Fp
           exit 1
         end
 
-        workspaces = result[:data]['workspaces'] || []
+        projects = result[:data]['projects'] || []
 
         output.success(result[:data]) do
-          if workspaces.empty?
+          if projects.empty?
             puts 'No projects found.'
           else
             headers = %w[SLUG NAME SURFACES]
-            rows = workspaces.map do |w|
-              surfaces = (w['available_surfaces'] || []).join(', ')
+            rows = projects.map do |w|
+              surfaces_result = client.list_surfaces(w['id'])
+              surface_keys = if surfaces_result[:ok]
+                               (surfaces_result[:data]['surfaces'] || []).map { |s| s['key'] }
+                             else
+                               []
+                             end
+              surfaces = surface_keys.join(', ')
               [w['slug'], w['name'], surfaces.empty? ? '-' : surfaces]
             end
             output.table(headers, rows)

data/lib/fp/commands/propose.rb

@@ -2,7 +2,7 @@
 
 module Fp
   module Commands
-    # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --acceptance "..." --parent <slug>
+    # fp propose --project <slug> --slug X --name "..." --why "..." --required a,b,c --acceptance "..." --parent <slug> --category <cat>
     # Create a new requirement as draft
     class Propose < Base
       KNOWN_FLAGS = {
@@ -12,9 +12,12 @@ module Fp
         why: :string,
         required: :string,
         acceptance: :string,
-        parent: :string
+        parent: :string,
+        category: :string
       }.freeze
 
+      VALID_CATEGORIES = %w[functional non-functional ux performance security compliance].freeze
+
       def run(args)
         opts, = parse_flags(args, KNOWN_FLAGS)
 
@@ -22,7 +25,13 @@ module Fp
         require_flag(opts, :slug, '--slug is required (immutable identifier for the requirement)')
         require_flag(opts, :name, '--name is required (human-readable title)')
 
-        workspace_id = resolve_workspace_id(opts[:project])
+        # Validate category client-side for better UX (fail fast with helpful message)
+        if opts[:category] && !VALID_CATEGORIES.include?(opts[:category])
+          output.error("Invalid category '#{opts[:category]}'. Must be one of: #{VALID_CATEGORIES.join(', ')}")
+          exit 1
+        end
+
+        project_id = resolve_project_id(opts[:project])
 
         # Parse required surfaces (comma-separated)
         required_surfaces = if opts[:required]
@@ -34,15 +43,16 @@ module Fp
         params = {
           slug: opts[:slug],
           title: opts[:name],
-          workspace_id: workspace_id,
+          project_id: project_id,
           required_surfaces: required_surfaces
         }
         params[:why] = opts[:why] if opts[:why]
         params[:acceptance] = opts[:acceptance] if opts[:acceptance]
+        params[:category] = opts[:category] if opts[:category]
 
         # Resolve parent slug to parent_id if provided
         if opts[:parent]
-          parent_id = resolve_parent_id(workspace_id, opts[:parent])
+          parent_id = resolve_parent_id(project_id, opts[:parent])
           params[:parent_id] = parent_id
         end
 
@@ -62,6 +72,7 @@ module Fp
           puts
           puts "  Title:    #{requirement['title']}"
           puts "  Status:   #{requirement['status']}"
+          puts "  Category: #{requirement['category'] || '(none)'}"
           puts "  Surfaces: #{(requirement['required_surfaces'] || []).join(', ')}"
           puts "  Parent:   #{opts[:parent] || '(none)'}" if opts[:parent]
           puts
@@ -74,8 +85,8 @@ module Fp
       private
 
       # Resolve a parent requirement slug to its ID
-      def resolve_parent_id(workspace_id, parent_slug)
-        result = client.list_requirements(workspace_id: workspace_id)
+      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
@@ -85,7 +96,7 @@ module Fp
         parent = requirements.find { |r| r['slug'] == parent_slug }
 
         unless parent
-          output.error("Parent requirement '#{parent_slug}' not found in this workspace")
+          output.error("Parent requirement '#{parent_slug}' not found in this project")
           exit 1
         end