feat: add support for explicit file arguments to validate command

Allows users to specify files directly on the command line:

  bin/codeownership validate file1.rb file2.rb

This provides a more flexible alternative to the --diff flag for
validating specific files. When explicit files are provided, they
take precedence over the --diff flag and a warning is displayed.

Changes:
- Updated CLI to accept file arguments after options
- Added warning when both --diff and explicit files are provided
- Added comprehensive specs for file argument behavior
- Updated README with usage examples

Author: martinemde

README.md

@@ -183,8 +183,15 @@ You can call the validation function with the Ruby API
 CodeOwnership.validate!
 ```
 or the CLI
-```
+```bash
+# Validate all files
 bin/codeownership validate
+
+# Validate specific files
+bin/codeownership validate path/to/file1.rb path/to/file2.rb
+
+# Validate only staged files
+bin/codeownership validate --diff
 ```
 
 ## Development

lib/code_ownership/cli.rb

@@ -37,7 +37,7 @@ def self.validate!(argv)
       options = {}
 
       parser = OptionParser.new do |opts|
-        opts.banner = "Usage: #{EXECUTABLE} validate [options]"
+        opts.banner = "Usage: #{EXECUTABLE} validate [options] [files...]"
 
         opts.on('--skip-autocorrect', 'Skip automatically correcting any errors, such as the .github/CODEOWNERS file') do
           options[:skip_autocorrect] = true
@@ -59,11 +59,22 @@ def self.validate!(argv)
       args = parser.order!(argv)
       parser.parse!(args)
 
-      files = if options[:diff]
+      # Collect any remaining arguments as file paths
+      specified_files = argv.reject { |arg| arg.start_with?('--') }
+
+      files = if !specified_files.empty?
+                # Files explicitly provided on command line
+                if options[:diff]
+                  $stderr.puts "Warning: Ignoring --diff flag because explicit files were provided"
+                end
+                specified_files.select { |file| File.exist?(file) }
+              elsif options[:diff]
+                # Staged files from git
                 ENV.fetch('CODEOWNERS_GIT_STAGED_FILES') { `git diff --staged --name-only` }.split("\n").select do |file|
                   File.exist?(file)
                 end
               else
+                # No files specified, validate all
                 nil
               end
 

spec/lib/code_ownership/cli_spec.rb

@@ -45,6 +45,49 @@
       end
     end
 
+    context 'with explicit file arguments' do
+      let(:argv) { ['validate', 'app/services/my_file.rb', 'frontend/javascripts/my_file.jsx'] }
+
+      it 'validates only the specified files' do
+        expect(CodeOwnership).to receive(:validate!) do |args|
+          expect(args[:files]).to match_array(['app/services/my_file.rb', 'frontend/javascripts/my_file.jsx'])
+          expect(args[:autocorrect]).to eq true
+          expect(args[:stage_changes]).to eq true
+        end
+        subject
+      end
+
+      context 'with options' do
+        let(:argv) { ['validate', '--skip-autocorrect', '--skip-stage', 'app/services/my_file.rb'] }
+
+        it 'passes the options correctly' do
+          expect(CodeOwnership).to receive(:validate!) do |args|
+            expect(args[:files]).to eq(['app/services/my_file.rb'])
+            expect(args[:autocorrect]).to eq false
+            expect(args[:stage_changes]).to eq false
+          end
+          subject
+        end
+      end
+
+      context 'when combined with --diff flag' do
+        let(:argv) { ['validate', '--diff', 'app/services/my_file.rb'] }
+
+        before do
+          allow(ENV).to receive(:fetch).and_call_original
+          allow(ENV).to receive(:fetch).with('CODEOWNERS_GIT_STAGED_FILES').and_return('other_file.rb')
+        end
+
+        it 'prioritizes explicit files over git diff and warns the user' do
+          expect($stderr).to receive(:puts).with("Warning: Ignoring --diff flag because explicit files were provided")
+          expect(CodeOwnership).to receive(:validate!) do |args|
+            expect(args[:files]).to eq(['app/services/my_file.rb'])
+          end
+          subject
+        end
+      end
+    end
+
     context 'with --diff argument' do
       let(:argv) { ['validate', '--diff'] }