this_is_ruby 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7cb3f275dd3475b96089c47a5dbef85a28240daae468e08fbac08e283afd6c96
-  data.tar.gz: 5ac450e2705dafa4176d89960356825d47511faeaf79e0f6420022bf18b403e3
+  metadata.gz: bff23b66de82379dceeca467cd82002a835bb61bd1baa375f9ffa9e4ac3b4472
+  data.tar.gz: c4da4c93d536106e2f1219b9f64745e66d7f1ea3e131d9f63e33528e553d3158
 SHA512:
-  metadata.gz: 275d332b9ff9b7b8039a58c77875f539d9e9769322df96b7cddfe1bb7e640ee0074312641e1fd0855b95b331563a71115c5bce3d8b4b51bb9bebb8326c1f4b89
-  data.tar.gz: fa0bbf5a22382f4da346e9c5725cd982635a9ab7dd2130efb19a98465b0a34f7eb20a0537e56a50d57d5a4ad86c9164c4335d7ba0600e611f663ee5f99846c04
+  metadata.gz: 76512697bf98d76e819adf43b873c7c9a94d3b74aad80776d1fde073b88306b973546fa05ee7150dac80d797b7ddb675fa3203e9e5ea448729a6825c83c27c28
+  data.tar.gz: bfe3b0b9c49b7231e344fdcc4a1854855ba52dfd0b18ce7f042dc74e1a308e4c0ec3c86eeba84940036592e146a1c399c7cc134bc8c992d19029fed81827c7a8

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.2.1
+
+- The managed block is now just the patterns between its two markers, down from
+  16 lines to 8. The preamble was the block explaining itself on top of a marker
+  that already names the gem, and the per-group comments repeated what the
+  report says at more length. `check` reports the file as out of date once after
+  upgrading; re-running writes the shorter block.
+
+## 0.2.0
+
+- Frontend sources are vendored by default. Telling GitHub a project is Ruby is
+  what the gem is for, and it read oddly to name that after a flag most people
+  would never pass. `--fair` keeps them counted, marking only what a tool wrote
+  or a generator copied in, for a repository whose frontend really is the point. `--all-frontend` is still accepted and does
+  nothing, so an existing CI step keeps working.
+- Reword the summary and description.
+
 ## 0.1.1
 
 - The "now" column no longer counts files that are already out of GitHub's

data/README.md

@@ -3,9 +3,9 @@
 [![Gem](https://img.shields.io/gem/v/this_is_ruby)](https://rubygems.org/gems/this_is_ruby)
 [![CI](https://github.com/evilmartians/this_is_ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/evilmartians/this_is_ruby/actions/workflows/ci.yml)
 
-GitHub decides a repository's language by counting bytes. Ruby code can often be outnumbered by sheer volume of JS/TS/HTML boilerplate. So GitHub labels the repo HTML or TypeScript.
+Ruby is one of the most eloquent and efficient languages, but it gets punished for it by GitHub's language attribution. A repository's language there is whichever one has the most bytes, and a Rails app, carefully designed to require next to no boilerplate code, easily ends up with less Ruby than JS, TS or HTML (ERB).
 
-This gem gives you controls.
+This gem tells GitHub: this is Ruby, by marking your frontend as `linguist-vendored`. No side effects on diffs or other DX.
 
 ## Install
 
@@ -40,24 +40,26 @@ $ this_is_ruby check    # exit 1 when .gitattributes is out of date
 | SimpleCov HTML reports, found by the report's own title | `linguist-generated` |
 | `db/structure.sql`, matching how Rails already treats `db/schema.rb` | `linguist-generated` |
 | shadcn/ui components, when `components.json` shows a generator put them there | `linguist-vendored` |
+| your frontend sources: `app/javascript/`, `app/frontend/`, `frontend/` | `linguist-vendored` |
 
 
-By default the gem only points at files a tool produced. On [inertia-rails/react-starter-kit][irsk], where GitHub counts TypeScript at 60.6%, that clears the HTML but leaves TypeScript the primary language.
+[irinanazarova/react-starter-kit-this-is-ruby][demo] is a fork of the Inertia Rails starter kit whose only change is the sixteen lines `this_is_ruby` wrote. Upstream, GitHub counts it as 60.6% TypeScript and 21.2% Ruby. The fork reads **82.6% Ruby, 1.1% TypeScript**. Compare its language bar with [the upstream one][irsk].
 
-## Make it Ruby
+## If your frontend really is the point
 
-If you think that despite a huge amount of hand-written JS/TS/HTML, the important work in your repository is Ruby, you can say so:
+Some repositories genuinely are TypeScript projects, and for those:
 
 ```console
-$ this_is_ruby --all-frontend
+$ this_is_ruby --fair
 ```
-On the same repository that marks `app/javascript/` as `linguist-vendored`, and
-GitHub then counts it as **82.6% Ruby, 1.1% TypeScript**. That is not an
-estimate: [irinanazarova/react-starter-kit-this-is-ruby][demo] is a fork of the
-kit whose only change is the sixteen lines this command wrote. Compare its
-language bar with [the upstream one][irsk].
 
-The one line that matters is which attribute it uses. [Generated files are suppressed in diffs][docs]; vendored files are not. So `--all-frontend` emits `linguist-vendored`, every source file keeps showing up in full in pull requests, and the only thing that changes is the color of the bar at the top of the page:
+That marks only the files nobody in the project wrote: every generated row in
+the table above, plus the shadcn components a generator copied in. Your own
+frontend keeps counting.
+
+## Why vendored and not generated
+
+The one line that matters is which attribute it uses. [Generated files are suppressed in diffs][docs]; vendored files are not. So your frontend is marked `linguist-vendored`, every source file keeps showing up in full in pull requests, and the only thing that changes is the color of the bar at the top of the page:
 
 ```console
 $ git check-attr linguist-vendored linguist-generated -- app/javascript/pages/home/index.tsx
@@ -77,8 +79,7 @@ On GitHub itself:
   plainly: these files "are suppressed in diffs". Reviewers get a "Load diff"
   button instead of the patch. The gem uses this attribute only for tool
   output; everything hand-written gets `linguist-vendored`, which leaves diffs
-  alone. That is why `--all-frontend` vendors your frontend rather than
-  marking it generated.
+  alone. That is why your frontend is vendored rather than marked generated.
 - **Code search still indexes the files.** They stay findable, and GitHub adds
   `is:generated` and `is:vendored` filters, so a query written as
   `-is:vendored` will skip them.

data/lib/this_is_ruby/attributes_file.rb

@@ -11,12 +11,6 @@ module ThisIsRuby
     END_MARKER = "# --- this_is_ruby: end ---"
     BLOCK = /^#{Regexp.escape(BEGIN_MARKER)}\n.*?^#{Regexp.escape(END_MARKER)}\n?/m
 
-    PREAMBLE = [
-      "# Managed by this_is_ruby. Re-run it when your build setup changes.",
-      "# Every path below is excluded from this repository's language stats.",
-      "# Edit above or below this block, never inside it."
-    ].freeze
-
     attr_reader :path
 
     def initialize(path)
@@ -65,13 +59,12 @@ module ThisIsRuby
       match ? [match.pre_match, match.post_match] : [current, ""]
     end
 
+    # Just the patterns, between two markers that name the gem. What each rule
+    # is for belongs in the report and the README, where there is room to say
+    # it properly, rather than as a comment in someone else's file.
     def block(emissions)
       body = "#{BEGIN_MARKER}\n"
-      PREAMBLE.each { |line| body << line << "\n" }
-      emissions.chunk_while { |a, b| a.rule == b.rule }.each do |group|
-        body << "\n# #{group.first.rule.summary}\n"
-        group.each { |emission| body << emission.line << "\n" }
-      end
+      emissions.each { |emission| body << emission.line << "\n" }
       body << END_MARKER << "\n"
     end
 

data/lib/this_is_ruby/cli.rb

@@ -27,7 +27,7 @@ module ThisIsRuby
       @argv = argv
       @out = out
       @err = err
-      @options = {path: ".", all_frontend: false, color: out.tty?}
+      @options = {path: ".", frontend: true, color: out.tty?}
     end
 
     def call
@@ -38,7 +38,7 @@ module ThisIsRuby
 
       repo = Repo.at(@options[:path])
       attributes = AttributesFile.new(repo.root.join(".gitattributes"))
-      plan = Plan.build(repo, attributes:, all_frontend: @options[:all_frontend])
+      plan = Plan.build(repo, attributes:, frontend: @options[:frontend])
       report = Report.new(plan, out: @out, color: @options[:color])
 
       send(command, plan, attributes, report)
@@ -78,7 +78,10 @@ module ThisIsRuby
       parser = OptionParser.new do |opts|
         opts.banner = USAGE
         opts.on("--path DIR", "repository to inspect (default: .)") { |dir| @options[:path] = dir }
-        opts.on("--all-frontend", "also mark hand-written frontend sources as vendored") { @options[:all_frontend] = true }
+        opts.on("--fair", "exclude only what a tool wrote or a generator copied in") { @options[:frontend] = false }
+        # 0.1.x asked for today's default with a flag. Accept the old name and
+        # do nothing, rather than break a CI step that still passes it.
+        opts.on("--all-frontend", "deprecated alias, now the default") { @options[:frontend] = true }
         opts.on("--[no-]color", "colourise output") { |on| @options[:color] = on }
         opts.on("-v", "--version", "print the version") do
           @out.puts VERSION

data/lib/this_is_ruby/plan.rb

@@ -7,9 +7,9 @@ module ThisIsRuby
 
     attr_reader :repo, :emissions, :declared
 
-    def self.build(repo, attributes:, all_frontend: false)
+    def self.build(repo, attributes:, frontend: true)
       spoken_for = spoken_for(attributes.existing_attributes)
-      found = Rules.for_level(all_frontend:).flat_map { |rule| rule.apply(repo) }
+      found = Rules.for_level(frontend:).flat_map { |rule| rule.apply(repo) }
       declared, emissions = found.partition do |emission|
         spoken_for.any? { |pattern| covers?(pattern, emission.pattern) }
       end

data/lib/this_is_ruby/rule.rb

@@ -7,10 +7,10 @@ module ThisIsRuby
   # Rules never guess: when the evidence is not on disk they return nothing,
   # so a project that has no coverage report gets no line about one.
   #
-  # :safe rules find files a tool produced, and always run. :frontend rules
-  # find hand-written sources, and run only with --all-frontend, because
-  # excluding those is the owner's call about what their repository is rather
-  # than a fact about who typed the file.
+  # :safe rules find files a tool produced. :frontend rules find hand-written
+  # sources, which is a claim about what the repository is rather than about
+  # who typed the file; both run by default, and --fair drops the second group
+  # for a project whose frontend really is the point.
   class Rule
     LEVELS = %i[safe frontend].freeze
 

data/lib/this_is_ruby/rules.rb

@@ -121,7 +121,7 @@ module ThisIsRuby
       Rule.new(
         key: :frontend_sources,
         attribute: "linguist-vendored",
-        summary: "frontend sources, excluded at your request (--all-frontend)",
+        summary: "frontend sources (pass --fair to keep them counted)",
         level: :frontend
       ) do |repo|
         present = FRONTEND_ROOTS.select { |dir| under(repo, dir).any? }
@@ -129,8 +129,8 @@ module ThisIsRuby
       end
     ].freeze
 
-    def for_level(all_frontend:)
-      all_frontend ? ALL : ALL.select(&:safe?)
+    def for_level(frontend:)
+      frontend ? ALL : ALL.select(&:safe?)
     end
   end
 end

data/lib/this_is_ruby/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ThisIsRuby
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: this_is_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Irina Nazarova
@@ -9,12 +9,10 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: |
-  GitHub picks a repository's language by counting bytes, and a Rails app
-  carries plenty it never authored: generated error pages, compiled assets,
-  coverage reports, components copied in by a frontend generator. Together
-  they routinely outweigh the app's own Ruby. this_is_ruby finds them and
-  writes the .gitattributes overrides Linguist already understands.
+description: |-
+  Ruby is one of the most eloquent and efficient languages, but it gets punished for it by GitHub's language attribution. Even more so, a Rails app, carefully designed to require next to no boilerplate code, easily ends up with less Ruby than JS, TS or HTML (ERB).
+
+  This gem tells GitHub: this is Ruby, by marking your frontend as "linguist-vendored". No side effects on diffs or other DX.
 email:
 - inazarova@evilmartians.com
 executables:
@@ -61,5 +59,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: Tell GitHub which files in your Ruby project nobody wrote
+summary: Tell GitHub your project is Ruby.
 test_files: []