this_is_ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a2047298c7f0c4729968ed6827707200b80ad5810ccde2c5fcd6fb009d4b662
-  data.tar.gz: 541e8c560fdb8441a4aa4ec0f040827a10454feb8bd467cad44840a614a05455
+  metadata.gz: 70cb32fbaddf28dbdae4e21b4b8e009fbda116b02c967ddf08b9618db5df4a0c
+  data.tar.gz: fe332fb48d5d355a59cb13b7ff1efe4aa403f2ed031aaa5e7f66924bd179bb62
 SHA512:
-  metadata.gz: f09cc8394377d79592a9e8e845a6da04c1dd4fcfa113ebebcf0460af1d8cc3b8c240f8e944048b9a471790d926e1d49123533546aaa093b111598255173de0f4
-  data.tar.gz: f4eeae23cde25381e1fd4132f6904e7c4f5a07a1980a8e7855e115d5532ad8c84fb6b25af916264b786e2ec64f2e93f1679597edddfe70c7c7251aea287f35c2
+  metadata.gz: 71f21c362ac2d542b6329f3082dd6de70b6f6b37d2c78c00a0a334ba371d20b76093673f23cb18bd5d9b86838c6c1647d4cf0527fc29f474794dbfc04d783a48
+  data.tar.gz: 28d66d7abd69c80304bc01ee5c848cbc35b918854c014dd81b38ed859a4e9dc985c00834a954b3a171b3a4ee88ded33794862c1a860350efc522fd3d9ff916e6

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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
+  language bar. It asks `git check-attr`, so Rails' own `db/schema.rb` line and
+  anything written by hand are honoured, and it subtracts only what this run
+  claims, so re-running on a repository already converted still shows the
+  contrast rather than reporting that nothing would change.
+
 ## 0.1.0
 
 Initial release.
@@ -8,18 +25,8 @@ Initial release.
   Webpacker and Vite builds, SimpleCov reports, SQL structure dumps and
   shadcn/ui components.
 - Writes a managed block in `.gitattributes`, leaving the rest of the file
-  untouched, and stays quiet about anything already declared there.
-- `plan`, `apply` and `check` commands; `--all-frontend` opt-in.
-
-## Unreleased
-
-- Exit 1 on an unknown command or option instead of 0, so a typo in a CI step
-  fails rather than silently skipping `check`.
-- Leave a path alone when its Linguist attribute is already decided, including
-  when it was explicitly unset (`-linguist-generated`) or made unspecified
-  (`!linguist-generated`). Writing our line after such a declaration reversed
-  it, because the last match wins.
-- Rewrite the managed block where it already sits, so content below it stays
-  below it.
-- Read `git rev-parse` from stdout alone: with `GIT_TRACE` set, or on any git
-  warning, the merged stream became part of the repository root.
+  untouched, and stays quiet about anything already decided there, including an
+  attribute the owner explicitly unset.
+- Rewrites the block where it sits, so content below it stays below it.
+- `plan`, `apply` and `check` commands; `--all-frontend` opt-in, which uses
+  `linguist-vendored` so diffs keep working.

data/README.md

@@ -1,8 +1,11 @@
 # this_is_ruby
 
-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.
+[![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)
 
-This gem gives you controls.
+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 tells GitHub: this is Ruby, by marking your frontend as `linguist-vendored`. No side effects on diffs or other DX.
 
 ## Install
 
@@ -12,6 +15,9 @@ group :development do
 end
 ```
 
+Or `gem install this_is_ruby` to run it against any repository without adding
+it to a project.
+
 ## Use
 
 ```console
@@ -34,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
@@ -71,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/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
@@ -65,8 +65,12 @@ module ThisIsRuby
       @claimed_paths ||= emissions.flat_map(&:paths).to_set
     end
 
-    def before = @before ||= LanguageEstimate.of(repo)
+    # The bar without our block: what GitHub reports today, minus the paths this
+    # run is claiming. Asking git means Rails' own `db/schema.rb` line and
+    # anything hand-written are honoured, while re-running on a repository we
+    # already converted still shows the contrast rather than "nothing changes".
+    def before = @before ||= LanguageEstimate.of(repo, excluding: repo.already_excluded - claimed_paths)
 
-    def after = @after ||= LanguageEstimate.of(repo, excluding: claimed_paths)
+    def after = @after ||= LanguageEstimate.of(repo, excluding: repo.already_excluded | claimed_paths)
   end
 end

data/lib/this_is_ruby/repo.rb

@@ -17,6 +17,9 @@ module ThisIsRuby
     # markers we check for all sit in the first few lines.
     PEEK_BYTES = 4096
 
+    # The attributes that take a file out of GitHub's language statistics.
+    LINGUIST_EXCLUSIONS = %w[linguist-generated linguist-vendored linguist-documentation].freeze
+
     attr_reader :root
 
     def self.at(path)
@@ -55,6 +58,17 @@ module ThisIsRuby
       full.open("rb") { |io| io.read(PEEK_BYTES) }
     end
 
+    # Paths git already reports as excluded from Linguist's counts, whoever
+    # declared them: our own block, the lines Rails generates, or something
+    # written by hand. Resolving the patterns ourselves would mean
+    # reimplementing gitignore matching, so ask git, which owns the answer.
+    def already_excluded
+      @already_excluded ||= begin
+        paths = tracked
+        paths.empty? ? Set.new : Set.new(check_attr(paths))
+      end
+    end
+
     def size(path)
       full = root.join(path)
       full.file? ? full.size : 0
@@ -62,6 +76,18 @@ module ThisIsRuby
 
     private
 
+    # `check-attr --stdin -z` reads NUL-separated paths and answers with
+    # NUL-separated (path, attribute, value) triples.
+    def check_attr(paths)
+      out, _err, status = Open3.capture3(
+        "git", "-C", root.to_s, "check-attr", "--stdin", "-z", *LINGUIST_EXCLUSIONS,
+        stdin_data: paths.join("\0")
+      )
+      return [] unless status.success?
+
+      out.split("\0").each_slice(3).filter_map { |path, _attribute, value| path if value == "set" }
+    end
+
     def tracked_set
       @tracked_set ||= tracked.to_set
     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.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: this_is_ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 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: []