Add strategy that was used to detect the file's language (#7405)

* Allow to know strategy used to detect language

* Adjust require statements

* Add tests

Author: DecimalTurn

bin/github-linguist

@@ -13,13 +13,14 @@ Linguist v#{Linguist::VERSION}
 Detect language type and determine language breakdown for a given Git repository.
 
 Usage: github-linguist <path>
-       github-linguist <path> [--rev REV] [--tree-size] [--breakdown] [--json]
-       github-linguist [--rev REV] [--tree-size] [--breakdown] [--json]
+       github-linguist <path> [--rev REV] [--tree-size] [--breakdown] [--strategies] [--json]
+       github-linguist [--rev REV] [--tree-size] [--breakdown] [--strategies] [--json]
 HELP
 
 def github_linguist(args)
   breakdown = false
   json_output = false
+  show_strategies = false
   tree_size = Linguist::Repository::MAX_TREE_SIZE
   rev = 'HEAD'
   path = Dir.pwd
@@ -29,6 +30,7 @@ def github_linguist(args)
     opts.version = Linguist::VERSION
 
     opts.on("-b", "--breakdown", "Analyze entire repository and display detailed usage statistics") { breakdown = true }
+    opts.on("-s", "--strategies", "Show language detection strategy used for each file") { show_strategies = true }
     opts.on("-j", "--json", "Output results as JSON") { json_output = true }
     opts.on("-r", "--rev REV", String,
             "Analyze specific git revision",
@@ -59,6 +61,11 @@ def github_linguist(args)
       puts "invalid revision '#{rev}' for repo '#{path}'"
       exit 1
     end
+
+    # Set up instrumentation to track detection strategies if requested
+    instrumenter = show_strategies ? Linguist::BasicInstrumenter.new : nil
+    Linguist.instrumenter = instrumenter
+
     repo = Linguist::Repository.new(rugged, target_oid, tree_size)
 
     full_results = {}
@@ -72,13 +79,18 @@ def github_linguist(args)
       full_results.sort_by { |_, v| v[:size] }.reverse.each do |language, details|
         puts "%-7s %-10s %s" % ["#{details[:percentage]}%", details[:size], language]
       end
-      if breakdown
+      if breakdown || show_strategies
         puts
         file_breakdown = repo.breakdown_by_file
         file_breakdown.each do |lang, files|
           puts "#{lang}:"
           files.each do |file|
-            puts file
+            strategy_info = instrumenter&.detected_info&.[](file)
+            if show_strategies && strategy_info
+              puts "  #{file} [#{strategy_info[:strategy]}]"
+            else
+              puts "  #{file}"
+            end
           end
           puts
         end
@@ -96,6 +108,9 @@ def github_linguist(args)
       end
     end
   elsif File.file?(path)
+    # Set up instrumentation to track detection strategies if requested
+    instrumenter = show_strategies ? Linguist::BasicInstrumenter.new : nil
+    Linguist.instrumenter = instrumenter
 
     begin
       # Check if this file is inside a git repository so we have things like
@@ -134,6 +149,10 @@ def github_linguist(args)
       puts "  type:      #{type}"
       puts "  mime type: #{blob.mime_type}"
       puts "  language:  #{blob.language}"
+      if show_strategies && blob.language
+        strategy_info = instrumenter.detected_info[blob.name]
+        puts "  strategy:  #{strategy_info[:strategy]}" if strategy_info
+      end
 
       if blob.large?
         puts "  blob is too large to be shown"

lib/linguist.rb

@@ -9,6 +9,7 @@
 require 'linguist/version'
 require 'linguist/strategy/manpage'
 require 'linguist/strategy/xml'
+require 'linguist/instrumenter'
 
 class << Linguist
   # Public: Detects the Language of the blob.

lib/linguist/instrumenter.rb

@@ -0,0 +1,19 @@
+module Linguist
+  class BasicInstrumenter
+    attr_reader :detected_info
+
+    def initialize
+      @detected_info = {}
+    end
+
+    def instrument(name, payload = {})
+      if name == "linguist.detected" && payload[:blob]
+        @detected_info[payload[:blob].name] = {
+          strategy: payload[:strategy].name.split("::").last,
+          language: payload[:language]&.name
+        }
+      end
+      yield if block_given?
+    end
+  end
+end

test/fixtures/Ruby/foo.rb

@@ -0,0 +1,11 @@
+# This file is used to test the Linguist language detection capabilities.
+# It should be detected as Ruby based on its extension and content.
+# The file is intentionally simple to ensure it does not contain complex logic.
+# You can add more Ruby code here if needed for further testing.
+# The purpose of this file is to serve as a fixture for testing the Linguist library.
+# It should not be executed in a production environment.
+# Ensure that this file is saved with the .rb extension to be recognized as Ruby code.
+
+puts "This is a sample Ruby file for testing purposes."
+
+

test/fixtures/Shell/sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# This is a comment
+echo "Hello, World!"  # Print a message to the console

test/fixtures/VBA/sample.bas

@@ -0,0 +1,20 @@
+Attribute VB_Name = "Utilities"
+Option Explicit
+
+Sub EditExcelRange()
+    Dim ws As Worksheet
+    Set ws = ThisWorkbook.Sheets("Sheet1")
+    
+    ' Edit a range in the worksheet
+    ws.Range("A1").Value = "Hello, World!"
+    ws.Range("A2").Value = 42
+    ws.Range("A3").Value = Date
+    
+    ' Format the range
+    With ws.Range("A1:A3")
+        .Font.Bold = True
+        .Interior.Color = RGB(255, 255, 0) ' Yellow background
+    End With
+    
+    MsgBox "Range edited successfully!"
+End Sub

test/test_basic_instrumenter.rb

@@ -0,0 +1,84 @@
+require_relative "./helper"
+
+class TestBasicInstrumenter < Minitest::Test
+  include Linguist
+
+  def setup
+    @instrumenter = Linguist::BasicInstrumenter.new
+    Linguist.instrumenter = @instrumenter
+  end
+
+  def teardown
+    Linguist.instrumenter = nil
+  end
+
+  def test_tracks_extension_strategy
+    # Ruby file detected by extension
+    blob = fixture_blob("Ruby/foo.rb")
+    Linguist.detect(blob)
+
+    assert @instrumenter.detected_info.key?(blob.name)
+    assert_equal "Extension", @instrumenter.detected_info[blob.name][:strategy]
+    assert_equal "Ruby", @instrumenter.detected_info[blob.name][:language]
+  end
+
+  def test_tracks_modeline_strategy
+    # File with vim modeline
+    blob = fixture_blob("Data/Modelines/ruby")
+    Linguist.detect(blob)
+
+    assert @instrumenter.detected_info.key?(blob.name)
+    assert_equal "Modeline", @instrumenter.detected_info[blob.name][:strategy]
+    assert_equal "Ruby", @instrumenter.detected_info[blob.name][:language]
+  end
+
+  def test_tracks_shebang_strategy
+    # File with shebang
+    blob = fixture_blob("Shell/sh")
+    Linguist.detect(blob)
+
+    assert @instrumenter.detected_info.key?(blob.name)
+    assert_equal "Shebang", @instrumenter.detected_info[blob.name][:strategy]
+    assert_equal "Shell", @instrumenter.detected_info[blob.name][:language]
+  end
+
+  def test_tracks_multiple_files
+    # Track multiple files in sequence
+    ruby_blob = fixture_blob("Ruby/foo.rb")
+    shell_blob = fixture_blob("Shell/sh")
+
+    Linguist.detect(ruby_blob)
+    Linguist.detect(shell_blob)
+
+    assert_equal 2, @instrumenter.detected_info.size
+    assert @instrumenter.detected_info.key?(ruby_blob.name)
+    assert @instrumenter.detected_info.key?(shell_blob.name)
+  end
+
+  def test_no_tracking_for_binary_files
+    binary_blob = fixture_blob("Binary/octocat.ai")
+    Linguist.detect(binary_blob)
+
+    # Should not record info for binary files
+    assert_equal 0, @instrumenter.detected_info.size
+  end
+
+  def test_records_correct_strategy_for_heuristics
+    # .bas file that should be detected via heuristics
+    blob = fixture_blob("VBA/sample.bas")
+    Linguist.detect(blob)
+
+    assert @instrumenter.detected_info.key?(blob.name)
+    assert_equal "Heuristics", @instrumenter.detected_info[blob.name][:strategy]
+  end
+
+  def test_tracks_filename_strategy
+    # Dockerfile detected by filename
+    blob = fixture_blob("Dockerfile/Dockerfile")
+    Linguist.detect(blob)
+
+    assert @instrumenter.detected_info.key?(blob.name)
+    assert_equal "Filename", @instrumenter.detected_info[blob.name][:strategy]
+    assert_equal "Dockerfile", @instrumenter.detected_info[blob.name][:language]
+  end
+end