Add manifest filtering and stateless parsing API

Author: andrew

CHANGELOG.md

@@ -5,6 +5,8 @@
 - `--format=json` support for `diff`, `tree`, `stale`, and `why` commands
 - Ignore go.sum (checksums only), treat go.mod as lockfile
 - Update ecosystems-bibliothecary to ~> 15.1
+- `--manifest` filter for `list` command to filter by manifest path
+- Stateless parsing API for forge integration (`Git::Pkgs.parse_file`, `parse_files`, `diff_file`)
 
 ## [0.6.1] - 2026-01-05
 

README.md

@@ -95,6 +95,7 @@ Snapshot Coverage
 git pkgs list
 git pkgs list --commit=abc123
 git pkgs list --ecosystem=rubygems
+git pkgs list --manifest=Gemfile
 ```
 
 Example output:
@@ -433,6 +434,37 @@ Actions, BentoML, Bower, Cargo, Carthage, Clojars, CocoaPods, Cog, Conda, CPAN,
 
 SBOM formats (CycloneDX, SPDX) are not supported as they duplicate information from the actual lockfiles.
 
+## Ruby API
+
+For embedding in other tools (like forges), git-pkgs provides a stateless parsing API that doesn't require initializing a database:
+
+```ruby
+require "git/pkgs"
+
+# Parse a single manifest file
+result = Git::Pkgs.parse_file("Gemfile", content)
+# => { platform: "rubygems", kind: "manifest", dependencies: [...] }
+
+# Parse multiple files at once
+results = Git::Pkgs.parse_files({
+  "Gemfile" => gemfile_content,
+  "package.json" => package_json_content
+})
+
+# Diff two versions of a manifest
+diff = Git::Pkgs.diff_file("Gemfile", old_content, new_content)
+# => { path: "Gemfile", platform: "rubygems", added: [...], modified: [...], removed: [...] }
+```
+
+The diff_file method returns modified dependencies with a `previous_requirement` field showing the old version.
+
+For database queries, connect to an existing database and use the Sequel models directly:
+
+```ruby
+Git::Pkgs::Database.connect(repo_git_dir)
+Git::Pkgs::Models::DependencyChange.where(name: "rails").all
+```
+
 ## Contributing
 
 Bug reports, feature requests, and pull requests are welcome. If you're unsure about a change, open an issue first to discuss it.

lib/git/pkgs.rb

@@ -47,6 +47,77 @@ class NotInGitRepoError < Error; end
     class << self
       attr_accessor :quiet, :git_dir, :work_tree, :db_path, :batch_size, :snapshot_interval, :threads
 
+      # Parse dependencies from a single manifest or lockfile.
+      # Returns nil if the file is not recognized as a manifest.
+      #
+      # @param path [String] file path (used for format detection)
+      # @param content [String] file contents
+      # @return [Hash, nil] parsed manifest with :platform, :path, :kind, :dependencies keys
+      def parse_file(path, content)
+        Config.configure_bibliothecary
+        result = Bibliothecary.analyse_file(path, content).first
+        return nil unless result
+        return nil if Config.filter_ecosystem?(result[:platform])
+
+        result
+      end
+
+      # Parse dependencies from multiple files.
+      # Returns only files that are recognized as manifests.
+      #
+      # @param files [Hash<String, String>] hash of path => content
+      # @return [Array<Hash>] array of parsed manifests
+      def parse_files(files)
+        Config.configure_bibliothecary
+        files.filter_map do |path, content|
+          result = Bibliothecary.analyse_file(path, content).first
+          next unless result
+          next if Config.filter_ecosystem?(result[:platform])
+
+          result
+        end
+      end
+
+      # Diff dependencies between two versions of a manifest file.
+      # Returns added, modified, and removed dependencies.
+      #
+      # @param path [String] file path (used for format detection)
+      # @param old_content [String] previous file contents (empty string for new files)
+      # @param new_content [String] current file contents (empty string for deleted files)
+      # @return [Hash] with :added, :modified, :removed arrays and :platform, :path keys
+      def diff_file(path, old_content, new_content)
+        Config.configure_bibliothecary
+
+        old_result = old_content.empty? ? nil : Bibliothecary.analyse_file(path, old_content).first
+        new_result = new_content.empty? ? nil : Bibliothecary.analyse_file(path, new_content).first
+
+        platform = new_result&.dig(:platform) || old_result&.dig(:platform)
+        return nil unless platform
+        return nil if Config.filter_ecosystem?(platform)
+
+        old_deps = (old_result&.dig(:dependencies) || []).map { |d| [d[:name], d] }.to_h
+        new_deps = (new_result&.dig(:dependencies) || []).map { |d| [d[:name], d] }.to_h
+
+        added = (new_deps.keys - old_deps.keys).map { |n| new_deps[n] }
+        removed = (old_deps.keys - new_deps.keys).map { |n| old_deps[n] }
+        modified = (old_deps.keys & new_deps.keys).filter_map do |name|
+          old_dep = old_deps[name]
+          new_dep = new_deps[name]
+          next if old_dep[:requirement] == new_dep[:requirement] && old_dep[:type] == new_dep[:type]
+
+          new_dep.to_h.merge(previous_requirement: old_dep[:requirement])
+        end
+
+        {
+          path: path,
+          platform: platform,
+          kind: new_result&.dig(:kind) || old_result&.dig(:kind),
+          added: added,
+          modified: modified,
+          removed: removed
+        }
+      end
+
       def configure_from_env
         @git_dir ||= presence(ENV["GIT_DIR"])
         @work_tree ||= presence(ENV["GIT_WORK_TREE"])

lib/git/pkgs/commands/list.rb

@@ -25,6 +25,10 @@ def run
           deps = compute_dependencies_at_commit(target_commit, repo)
 
           # Apply filters
+          if @options[:manifest]
+            deps = deps.select { |d| d[:manifest_path] == @options[:manifest] }
+          end
+
           if @options[:ecosystem]
             deps = deps.select { |d| d[:ecosystem] == @options[:ecosystem] }
           end
@@ -133,6 +137,10 @@ def parse_options
               options[:ecosystem] = v
             end
 
+            opts.on("-m", "--manifest=PATH", "Filter by manifest path") do |v|
+              options[:manifest] = v
+            end
+
             opts.on("-t", "--type=TYPE", "Filter by dependency type") do |v|
               options[:type] = v
             end

test/git/pkgs/test_cli.rb

@@ -1849,6 +1849,89 @@ def test_list_filters_by_ecosystem
 
     assert_includes output, "No dependencies found"
   end
+
+  def test_list_filters_by_manifest
+    sha = SecureRandom.hex(20)
+    commit = Git::Pkgs::Models::Commit.create(
+      sha: sha, message: "Add deps",
+      author_name: "alice", author_email: "alice@example.com",
+      committed_at: Time.now, has_dependency_changes: true
+    )
+
+    gemfile = Git::Pkgs::Models::Manifest.find_or_create(path: "Gemfile", ecosystem: "rubygems", kind: "manifest")
+    package_json = Git::Pkgs::Models::Manifest.find_or_create(path: "package.json", ecosystem: "npm", kind: "manifest")
+
+    branch = Git::Pkgs::Models::Branch.create(name: "main", last_analyzed_sha: sha)
+    Git::Pkgs::Models::BranchCommit.create(branch: branch, commit: commit, position: 1)
+
+    Git::Pkgs::Models::DependencySnapshot.create(
+      commit: commit, manifest: gemfile, name: "rails",
+      ecosystem: "rubygems", requirement: "~> 7.0", dependency_type: "runtime"
+    )
+    Git::Pkgs::Models::DependencySnapshot.create(
+      commit: commit, manifest: package_json, name: "lodash",
+      ecosystem: "npm", requirement: "^4.0", dependency_type: "runtime"
+    )
+
+    output = capture_stdout do
+      Dir.chdir(@test_dir) do
+        Git::Pkgs::Commands::List.new(["--commit=#{sha}", "--manifest=Gemfile"]).run
+      end
+    end
+
+    assert_includes output, "rails"
+    refute_includes output, "lodash"
+  end
+
+  def test_list_manifest_filter_no_match
+    commit = create_commit_with_changes("alice", [
+      { name: "rails", change_type: "added" }
+    ])
+    create_branch_with_snapshot("main", commit, [{ name: "rails" }])
+
+    output = capture_stdout do
+      Dir.chdir(@test_dir) do
+        Git::Pkgs::Commands::List.new(["--commit=#{commit.sha}", "--manifest=package.json"]).run
+      end
+    end
+
+    assert_includes output, "No dependencies found"
+  end
+
+  def test_list_manifest_filter_json_format
+    sha = SecureRandom.hex(20)
+    commit = Git::Pkgs::Models::Commit.create(
+      sha: sha, message: "Add deps",
+      author_name: "alice", author_email: "alice@example.com",
+      committed_at: Time.now, has_dependency_changes: true
+    )
+
+    gemfile = Git::Pkgs::Models::Manifest.find_or_create(path: "Gemfile", ecosystem: "rubygems", kind: "manifest")
+    package_json = Git::Pkgs::Models::Manifest.find_or_create(path: "package.json", ecosystem: "npm", kind: "manifest")
+
+    branch = Git::Pkgs::Models::Branch.create(name: "main", last_analyzed_sha: sha)
+    Git::Pkgs::Models::BranchCommit.create(branch: branch, commit: commit, position: 1)
+
+    Git::Pkgs::Models::DependencySnapshot.create(
+      commit: commit, manifest: gemfile, name: "rails",
+      ecosystem: "rubygems", requirement: "~> 7.0", dependency_type: "runtime"
+    )
+    Git::Pkgs::Models::DependencySnapshot.create(
+      commit: commit, manifest: package_json, name: "lodash",
+      ecosystem: "npm", requirement: "^4.0", dependency_type: "runtime"
+    )
+
+    output = capture_stdout do
+      Dir.chdir(@test_dir) do
+        Git::Pkgs::Commands::List.new(["--commit=#{sha}", "--manifest=Gemfile", "--format=json"]).run
+      end
+    end
+
+    data = JSON.parse(output)
+    assert_equal 1, data.length
+    assert_equal "rails", data.first["name"]
+    assert_equal "Gemfile", data.first["manifest_path"]
+  end
 end
 
 class Git::Pkgs::TestStaleCommand < Git::Pkgs::CommandTestBase