git-pkgs 0.2.0 → 0.4.0

data/README.md

@@ -146,6 +146,7 @@ Show who added each current dependency:
 ```bash
 git pkgs blame
 git pkgs blame --ecosystem=rubygems
+git pkgs praise  # alias for blame
 ```
 
 Example output:
@@ -167,8 +168,10 @@ Gemfile (rubygems):
 
 ```bash
 git pkgs stats
-git pkgs stats --by-author       # who added the most dependencies
-git pkgs stats --ecosystem=npm   # filter by ecosystem
+git pkgs stats --by-author         # who added the most dependencies
+git pkgs stats --ecosystem=npm     # filter by ecosystem
+git pkgs stats --since=2024-01-01  # changes after date
+git pkgs stats --until=2024-12-31  # changes before date
 ```
 
 Example output:
@@ -225,6 +228,17 @@ git pkgs tree --ecosystem=rubygems
 
 This shows dependencies grouped by type (runtime, development, etc).
 
+### Find stale dependencies
+
+```bash
+git pkgs stale                  # list deps by how long since last touched
+git pkgs stale --days=365       # only show deps untouched for a year
+git pkgs stale --ecosystem=npm  # filter by ecosystem
+git pkgs outdated               # alias for stale
+```
+
+Shows dependencies sorted by how long since they were last changed in your repo. Useful for finding packages that may have been forgotten or need review.
+
 ### Diff between commits
 
 ```bash
@@ -244,6 +258,33 @@ git pkgs show HEAD~5       # relative ref
 
 Like `git show` but for dependencies. Shows what was added, modified, or removed in a single commit.
 
+### Find where a package is declared
+
+```bash
+git pkgs where rails           # find in manifest files
+git pkgs where lodash -C 2     # show 2 lines of context
+git pkgs where express --ecosystem=npm
+```
+
+Shows which manifest files declare a package and the exact line:
+
+```
+Gemfile:5:gem "rails", "~> 7.0"
+Gemfile.lock:142:    rails (7.0.8)
+```
+
+Like `grep` but scoped to manifest files that git-pkgs knows about.
+
+### List commits with dependency changes
+
+```bash
+git pkgs log                  # recent commits with dependency changes
+git pkgs log --author=alice   # filter by author
+git pkgs log -n 50            # show more commits
+```
+
+Like `git log` but only shows commits that changed dependencies, with the changes listed under each commit.
+
 ### Keep database updated
 
 After the initial analysis, you can incrementally update the database with new commits:
@@ -258,6 +299,27 @@ You can also install git hooks to update automatically after commits and merges:
 git pkgs hooks --install
 ```
 
+### Upgrading
+
+After updating git-pkgs, you may need to rebuild the database if the schema has changed:
+
+```bash
+git pkgs upgrade
+```
+
+This is detected automatically and you'll see a message if an upgrade is needed.
+
+### Show database schema
+
+```bash
+git pkgs schema                   # human-readable table format
+git pkgs schema --format=sql      # CREATE TABLE statements
+git pkgs schema --format=json     # JSON structure
+git pkgs schema --format=markdown # markdown tables
+```
+
+Useful for understanding the [database structure](docs/schema.md) or generating documentation.
+
 ### CI usage
 
 You can run git-pkgs in CI to show dependency changes in pull requests:
@@ -283,6 +345,43 @@ jobs:
       - run: git pkgs diff --from=origin/${{ github.base_ref }} --to=HEAD
 ```
 
+### Diff driver
+
+Install a git textconv driver that shows semantic dependency changes instead of raw lockfile diffs:
+
+```bash
+git pkgs diff-driver --install
+```
+
+Now `git diff` on lockfiles shows a sorted dependency list instead of raw lockfile changes:
+
+```diff
+diff --git a/Gemfile.lock b/Gemfile.lock
+--- a/Gemfile.lock
++++ b/Gemfile.lock
+@@ -1,3 +1,3 @@
++kamal 1.0.0
+-puma 5.0.0
++puma 6.0.0
+ rails 7.0.0
+-sidekiq 6.0.0
+```
+
+Use `git diff --no-textconv` to see the raw lockfile diff. To remove: `git pkgs diff-driver --uninstall`
+
+## Configuration
+
+git-pkgs respects [standard git configuration](https://git-scm.com/docs/git-config).
+
+**Colors** are enabled when writing to a terminal. Disable with `NO_COLOR=1`, `git config color.ui never`, or `git config color.pkgs never` for git-pkgs only.
+
+**Pager** follows git's precedence: `GIT_PAGER` env, `core.pager` config, `PAGER` env, then `less -FRSX`. Use `--no-pager` flag or `git config core.pager cat` to disable.
+
+**Environment variables:**
+
+- `GIT_DIR` - git directory location (standard git variable)
+- `GIT_PKGS_DB` - database path (default: `.git/pkgs.sqlite3`)
+
 ## Performance
 
 Benchmarked on a MacBook Pro analyzing [octobox](https://github.com/octobox/octobox) (5191 commits, 8 years of history): init takes about 18 seconds at roughly 300 commits/sec, producing an 8.3 MB database. About half the commits (2531) had dependency changes.

data/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please email andrewnez@gmail.com.
+
+Do not open a public issue for security vulnerabilities.

data/lib/git/pkgs/analyzer.rb

@@ -46,7 +46,7 @@ module Git
       QUICK_MANIFEST_REGEX = Regexp.union(
         QUICK_MANIFEST_PATTERNS.map do |pattern|
           if pattern.include?('*')
-            Regexp.new(pattern.gsub('.', '\\.').gsub('*', '.*'))
+            Regexp.new(Regexp.escape(pattern).gsub('\\*', '.*'))
           else
             /(?:^|\/)#{Regexp.escape(pattern)}$/
           end

data/lib/git/pkgs/cli.rb

@@ -5,7 +5,8 @@ require "optparse"
 module Git
   module Pkgs
     class CLI
-      COMMANDS = %w[init update hooks info list tree history search why blame outdated stats diff branch show].freeze
+      COMMANDS = %w[init update hooks info list tree history search where why blame stale stats diff branch show log upgrade schema diff-driver].freeze
+      ALIASES = { "praise" => "blame", "outdated" => "stale" }.freeze
 
       def self.run(args)
         new(args).run
@@ -24,7 +25,7 @@ module Git
           print_help
         when "-v", "--version", "version"
           puts "git-pkgs #{Git::Pkgs::VERSION}"
-        when *COMMANDS
+        when *COMMANDS, *ALIASES.keys
           run_command(command)
         else
           $stderr.puts "Unknown command: #{command}"
@@ -34,7 +35,10 @@ module Git
       end
 
       def run_command(command)
-        command_class = Commands.const_get(command.capitalize.gsub(/_([a-z])/) { $1.upcase })
+        command = ALIASES.fetch(command, command)
+        # Convert kebab-case or snake_case to PascalCase
+        class_name = command.split(/[-_]/).map(&:capitalize).join
+        command_class = Commands.const_get(class_name)
         command_class.new(@args).run
       rescue NameError
         $stderr.puts "Command '#{command}' not yet implemented"
@@ -55,12 +59,16 @@ module Git
             tree      Show dependency tree grouped by type
             history   Show the history of a package
             search    Find a dependency across all history
+            where     Show where a package appears in manifest files
             why       Explain why a dependency exists
             blame     Show who added each dependency
-            outdated  Show dependencies that haven't been updated
+            stale     Show dependencies that haven't been updated
             stats     Show dependency statistics
             diff      Show dependency changes between commits
             show      Show dependency changes in a commit
+            log       List commits with dependency changes
+            upgrade   Upgrade database after git-pkgs update
+            schema    Show database schema
 
           Options:
             -h, --help     Show this help message

data/lib/git/pkgs/color.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Git
+  module Pkgs
+    module Color
+      CODES = {
+        red: 31,
+        green: 32,
+        yellow: 33,
+        blue: 34,
+        magenta: 35,
+        cyan: 36,
+        bold: 1,
+        dim: 2
+      }.freeze
+
+      def self.enabled?
+        return @enabled if defined?(@enabled)
+
+        @enabled = determine_color_support
+      end
+
+      def self.enabled=(value)
+        @enabled = value
+      end
+
+      def self.reset!
+        remove_instance_variable(:@enabled) if defined?(@enabled)
+      end
+
+      def self.determine_color_support
+        # NO_COLOR takes precedence (https://no-color.org/)
+        return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?
+        return false if ENV["TERM"] == "dumb"
+
+        # Check git config: color.pkgs takes precedence over color.ui
+        git_color = git_color_config
+        case git_color
+        when "always" then return true
+        when "never" then return false
+        # "auto" falls through to TTY check
+        end
+
+        $stdout.respond_to?(:tty?) && $stdout.tty?
+      end
+
+      def self.git_color_config
+        # color.pkgs overrides color.ui for git-pkgs specific control
+        pkgs_color = `git config --get color.pkgs 2>/dev/null`.chomp
+        return normalize_color_value(pkgs_color) unless pkgs_color.empty?
+
+        ui_color = `git config --get color.ui 2>/dev/null`.chomp
+        return normalize_color_value(ui_color) unless ui_color.empty?
+
+        "auto"
+      end
+
+      def self.normalize_color_value(value)
+        case value.downcase
+        when "true", "always" then "always"
+        when "false", "never" then "never"
+        else "auto"
+        end
+      end
+
+      def self.colorize(text, *codes)
+        return text unless enabled?
+
+        code_str = codes.map { |c| CODES[c] || c }.join(";")
+        "\e[#{code_str}m#{text}\e[0m"
+      end
+
+      def self.red(text)     = colorize(text, :red)
+      def self.green(text)   = colorize(text, :green)
+      def self.yellow(text)  = colorize(text, :yellow)
+      def self.blue(text)    = colorize(text, :blue)
+      def self.magenta(text) = colorize(text, :magenta)
+      def self.cyan(text)    = colorize(text, :cyan)
+      def self.bold(text)    = colorize(text, :bold)
+      def self.dim(text)     = colorize(text, :dim)
+    end
+  end
+end

data/lib/git/pkgs/commands/blame.rb

@@ -4,6 +4,8 @@ module Git
   module Pkgs
     module Commands
       class Blame
+        include Output
+
         def initialize(args)
           @args = args
           @options = parse_options
@@ -11,11 +13,7 @@ module Git
 
         def run
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
@@ -23,10 +21,7 @@ module Git
           branch_name = @options[:branch] || repo.default_branch
           branch = Models::Branch.find_by(name: branch_name)
 
-          unless branch&.last_analyzed_sha
-            $stderr.puts "No analysis found for branch '#{branch_name}'"
-            exit 1
-          end
+          error "No analysis found for branch '#{branch_name}'" unless branch&.last_analyzed_sha
 
           current_commit = Models::Commit.find_by(sha: branch.last_analyzed_sha)
           snapshots = current_commit&.dependency_snapshots&.includes(:manifest) || []
@@ -36,7 +31,7 @@ module Git
           end
 
           if snapshots.empty?
-            puts "No dependencies found"
+            empty_result "No dependencies found"
             return
           end
 
@@ -74,20 +69,24 @@ module Git
             end
             puts JSON.pretty_generate(json_data)
           else
-            grouped = blame_data.group_by { |d| [d[:manifest], d[:ecosystem]] }
+            paginate { output_text(blame_data) }
+          end
+        end
+
+        def output_text(blame_data)
+          grouped = blame_data.group_by { |d| [d[:manifest], d[:ecosystem]] }
 
-            grouped.each do |(manifest, ecosystem), deps|
-              puts "#{manifest} (#{ecosystem}):"
+          grouped.each do |(manifest, ecosystem), deps|
+            puts "#{manifest} (#{ecosystem}):"
 
-              max_name_len = deps.map { |d| d[:name].length }.max
-              max_author_len = deps.map { |d| d[:author].length }.max
+            max_name_len = deps.map { |d| d[:name].length }.max
+            max_author_len = deps.map { |d| d[:author].length }.max
 
-              deps.sort_by { |d| d[:name] }.each do |dep|
-                date = dep[:date].strftime("%Y-%m-%d")
-                puts "  #{dep[:name].ljust(max_name_len)}  #{dep[:author].ljust(max_author_len)}  #{date}  #{dep[:sha]}"
-              end
-              puts
+            deps.sort_by { |d| d[:name] }.each do |dep|
+              date = dep[:date].strftime("%Y-%m-%d")
+              puts "  #{dep[:name].ljust(max_name_len)}  #{dep[:author].ljust(max_author_len)}  #{date}  #{dep[:sha]}"
             end
+            puts
           end
         end
 
@@ -102,7 +101,7 @@ module Git
         def parse_coauthors(message)
           return [] unless message
 
-          message.scan(/^Co-authored-by:\s*(.+?)\s*<[^>]+>/i).flatten
+          message.scan(/^Co-authored-by:([^<]+)<[^>]+>/i).flatten.map(&:strip)
         end
 
         def bot_author?(name)
@@ -127,6 +126,10 @@ module Git
               options[:format] = v
             end
 
+            opts.on("--no-pager", "Do not pipe output into a pager") do
+              options[:no_pager] = true
+            end
+
             opts.on("-h", "--help", "Show this help") do
               puts opts
               exit

data/lib/git/pkgs/commands/branch.rb

@@ -4,6 +4,8 @@ module Git
   module Pkgs
     module Commands
       class Branch
+        include Output
+
         BATCH_SIZE = 100
         SNAPSHOT_INTERVAL = 20
 
@@ -25,32 +27,20 @@ module Git
           when nil, "-h", "--help"
             print_help
           else
-            $stderr.puts "Unknown subcommand: #{subcommand}"
-            $stderr.puts "Run 'git pkgs branch --help' for usage"
-            exit 1
+            error "Unknown subcommand: #{subcommand}. Run 'git pkgs branch --help' for usage"
           end
         end
 
         def add_branch
           branch_name = @args.shift
-          unless branch_name
-            $stderr.puts "Usage: git pkgs branch add <name>"
-            exit 1
-          end
+          error "Usage: git pkgs branch add <name>" unless branch_name
 
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
-          unless repo.branch_exists?(branch_name)
-            $stderr.puts "Branch '#{branch_name}' not found"
-            exit 1
-          end
+          error "Branch '#{branch_name}' not found" unless repo.branch_exists?(branch_name)
 
           existing = Models::Branch.find_by(name: branch_name)
           if existing
@@ -84,18 +74,14 @@ module Git
 
         def list_branches
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
           branches = Models::Branch.all
 
           if branches.empty?
-            puts "No branches tracked"
+            empty_result "No branches tracked"
             return
           end
 
@@ -110,25 +96,15 @@ module Git
 
         def remove_branch
           branch_name = @args.shift
-          unless branch_name
-            $stderr.puts "Usage: git pkgs branch remove <name>"
-            exit 1
-          end
+          error "Usage: git pkgs branch remove <name>" unless branch_name
 
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
           branch = Models::Branch.find_by(name: branch_name)
-          unless branch
-            $stderr.puts "Branch '#{branch_name}' not tracked"
-            exit 1
-          end
+          error "Branch '#{branch_name}' not tracked" unless branch
 
           # Only delete branch_commits, keep shared commits
           count = branch.branch_commits.count

data/lib/git/pkgs/commands/diff.rb

@@ -4,6 +4,8 @@ module Git
   module Pkgs
     module Commands
       class Diff
+        include Output
+
         def initialize(args)
           @args = args
           @options = parse_options
@@ -11,48 +13,27 @@ module Git
 
         def run
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
           from_ref = @options[:from]
           to_ref = @options[:to] || "HEAD"
 
-          unless from_ref
-            $stderr.puts "Usage: git pkgs diff --from=REF [--to=REF]"
-            exit 1
-          end
+          error "Usage: git pkgs diff --from=REF [--to=REF]" unless from_ref
 
           # Resolve git refs (like HEAD~10) to SHAs
           from_sha = repo.rev_parse(from_ref)
           to_sha = repo.rev_parse(to_ref)
 
-          unless from_sha
-            $stderr.puts "Could not resolve '#{from_ref}'"
-            exit 1
-          end
-
-          unless to_sha
-            $stderr.puts "Could not resolve '#{to_ref}'"
-            exit 1
-          end
+          error "Could not resolve '#{from_ref}'" unless from_sha
+          error "Could not resolve '#{to_ref}'" unless to_sha
 
           from_commit = find_or_create_commit(repo, from_sha)
           to_commit = find_or_create_commit(repo, to_sha)
 
-          unless from_commit
-            $stderr.puts "Commit '#{from_sha[0..7]}' not found"
-            exit 1
-          end
-
-          unless to_commit
-            $stderr.puts "Commit '#{to_sha[0..7]}' not found"
-            exit 1
-          end
+          error "Commit '#{from_sha[0..7]}' not found" unless from_commit
+          error "Commit '#{to_sha[0..7]}' not found" unless to_commit
 
           # Get all changes between the two commits
           changes = Models::DependencyChange
@@ -67,10 +48,14 @@ module Git
           end
 
           if changes.empty?
-            puts "No dependency changes between #{from_commit.short_sha} and #{to_commit.short_sha}"
+            empty_result "No dependency changes between #{from_commit.short_sha} and #{to_commit.short_sha}"
             return
           end
 
+          paginate { output_text(from_commit, to_commit, changes) }
+        end
+
+        def output_text(from_commit, to_commit, changes)
           puts "Dependency changes from #{from_commit.short_sha} to #{to_commit.short_sha}:"
           puts
 
@@ -79,35 +64,38 @@ module Git
           removed = changes.select { |c| c.change_type == "removed" }
 
           if added.any?
-            puts "Added:"
+            puts Color.green("Added:")
             added.group_by(&:name).each do |name, pkg_changes|
               latest = pkg_changes.last
-              puts "  + #{name} #{latest.requirement} (#{latest.manifest.path})"
+              puts Color.green("  + #{name} #{latest.requirement} (#{latest.manifest.path})")
             end
             puts
           end
 
           if modified.any?
-            puts "Modified:"
+            puts Color.yellow("Modified:")
             modified.group_by(&:name).each do |name, pkg_changes|
               first = pkg_changes.first
               latest = pkg_changes.last
-              puts "  ~ #{name} #{first.previous_requirement} -> #{latest.requirement}"
+              puts Color.yellow("  ~ #{name} #{first.previous_requirement} -> #{latest.requirement}")
             end
             puts
           end
 
           if removed.any?
-            puts "Removed:"
+            puts Color.red("Removed:")
             removed.group_by(&:name).each do |name, pkg_changes|
               latest = pkg_changes.last
-              puts "  - #{name} (was #{latest.requirement})"
+              puts Color.red("  - #{name} (was #{latest.requirement})")
             end
             puts
           end
 
           # Summary
-          puts "Summary: +#{added.map(&:name).uniq.count} -#{removed.map(&:name).uniq.count} ~#{modified.map(&:name).uniq.count}"
+          added_count = Color.green("+#{added.map(&:name).uniq.count}")
+          removed_count = Color.red("-#{removed.map(&:name).uniq.count}")
+          modified_count = Color.yellow("~#{modified.map(&:name).uniq.count}")
+          puts "Summary: #{added_count} #{removed_count} #{modified_count}"
         end
 
         def find_or_create_commit(repo, sha)
@@ -149,6 +137,10 @@ module Git
               options[:ecosystem] = v
             end
 
+            opts.on("--no-pager", "Do not pipe output into a pager") do
+              options[:no_pager] = true
+            end
+
             opts.on("-h", "--help", "Show this help") do
               puts opts
               exit