exhale 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cadf9f2ab741c8b3067a4b0a0fc455e850c932b9d64d1958dc4b3aa95b48e3e8
+  data.tar.gz: af11c04726fbf8871630d55c15334789dccab422aa7993a650266715ffd9e3f8
+SHA512:
+  metadata.gz: 122094bca81d07462b84ee61d363672e6e5d3526c1e5ff634682cce17fc328355bd6db9b7949d671b492334949cb9c14d287f5bd128866842d4b7952063f9667
+  data.tar.gz: da79c22a530eabefc86315cdf14d2a519b283efb30e244fc8dcec187613f38a7b1f694ba62e8eeb737103c9bf74e3f42b9e1fdf06a14fcc7b665ff35d530b7bf

data/.ruby-version

@@ -0,0 +1 @@
+3.3.4

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First release. `exhale dry` sweeps the whole codebase for duplicated Ruby and HTML ERB and fails while any copy isn't kept by the Contract.
+
+- Units from Prism (methods, Rails DSL bodies, concerns) and Herb (HTML ERB templates), normalized so the names of operations survive and the names of things become markers.
+- Rarity-weighted Jaccard over subtree fingerprints, with exact prefix filtering for whole units, exact subtree digests for copied fragments, and statement-run seeds for code lifted out of the middle of a method.
+- The verdict depends only on the commit. The merge base labels each finding introduced, shifted, already there, kept or contracted, and `--introduced-only` is the on-ramp for codebases that don't sweep clean yet.
+- The Contract under `contract/<primitive>/` keeps deliberate duplication (`parallel`), maps primitives to code (`covers`) and holds settings (`settings`). Stale clauses and unknown references fail the gate.
+- Text, JSON and EDN reports. EDN uses the shape Uncle Bob's dryer writes.
+- exhale ships with its own Contract (64 obligations, all executable), a clean run on itself, and a mutation gate where every Mutineer mutant is killed or listed with a reason.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obie Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# exhale
+
+<p align="center"><img src="assets/huff-exhale.png" alt="Huff, the Impatient Programming imp, blowing three identical cards into one while his robot watches from the leash" width="320"></p>
+
+exhale is the contraction gate for Rails. It fails a pull request while the codebase it leaves behind holds duplicated code the Contract doesn't keep, and it tells the agent doing the cleanup which original each copy should fold into.
+
+Agents duplicate by default. They read the codebase, find a shape that works, and copy it. When pull requests merge without a person reading every diff, the copy reaches main unless a machine stops it, and every session after that copies it again. exhale is that machine for the exhale half of the breath: expand to learn, then contract what you learned into what already exists, in the same PR.
+
+The first check is `exhale dry`. It combines Uncle Bob's [dryer](https://github.com/unclebob/dryer) and Ryan Davis's [flay](https://github.com/seattlerb/flay), rebuilt on [Prism](https://github.com/ruby/prism) and [Herb](https://herb-tools.dev) so it reads modern Ruby and ERB the way Rails writes them.
+
+## Install
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "exhale", require: false
+end
+```
+
+```bash
+bundle install
+bundle binstubs exhale
+bin/exhale
+```
+
+Exit code 0 means the codebase is clean. 1 means the gate failed: there's unkept duplication, or a Contract clause is stale or names code that doesn't exist. 2 means exhale couldn't run, usually because a file doesn't parse.
+
+## What it compares
+
+Units are methods, the bodies of Rails DSL calls (`scope`, `validate`, callbacks, `before_action` blocks), and ERB templates. Inside each unit it also compares fragments: blocks, conditionals, HTML elements, and runs of three or more consecutive statements lifted out of the middle of a method.
+
+Class-body declarations like `has_many` and `validates` never count, and neither does anything under `db/`, `config/`, `vendor/` or `tmp/`. Tests are left out unless you pass `--include-tests`, because tests should be DAMP, not DRY.
+
+Normalization keeps the names of operations and drops the names of things. Method names at call sites survive, so do operators, HTML tags and Stimulus `data-controller` values. Locals, instance variables, constants, symbols and literals become markers. These two methods are the same shape:
+
+```ruby
+def alpha(xs)
+  ys = xs.select(&:odd?)
+  ys.map(&:succ)
+end
+
+def beta(items)
+  kept = items.select(&:even?)
+  kept.map(&:pred)
+end
+```
+
+## Scoring
+
+Every subtree of a normalized unit is a fingerprint. Each fingerprint is weighted by how rare it is, `ln(1 + 1000 / count)`, and two units score by Jaccard similarity over those weights. A shape that shows up in every controller weighs close to nothing, so scaffolding doesn't drown out real copies. The default threshold is 0.80, with floors of 4 lines and 20 normalized nodes.
+
+## The gate
+
+Every run sweeps the whole codebase. Main passes the same gate, so anything a pull request trips over is its own doing. exhale compares against the merge base only to label findings:
+
+| Label | Meaning |
+| --- | --- |
+| Introduced | The PR touched one side, and the pair didn't match at the base |
+| Shifted | Neither side was touched, but the PR's changes moved the weights enough to push the pair over |
+| Already there | The pair matched at the base too |
+
+The report also lists what the PR contracted: pairs that matched at the base and don't anymore.
+
+An existing app won't sweep clean on its first run. `--introduced-only` gates on introduced and shifted findings and lists the rest as warnings. Once main is clean, drop the flag.
+
+## The Contract
+
+Deliberate duplication is a design decision, so it's declared in the Contract next to its reason. The Contract is organized by primitive, and each kind of analysis has its own file inside the primitive:
+
+```text
+contract/
+  provider_adapter/
+    README.md        the primitive's prose, plus a covers block
+    duplication.md   duplication it keeps, why, and its settings
+```
+
+A `parallel` block declares units that stay parallel on purpose. Its reason is the section it sits in:
+
+````markdown
+## Adapters stay independent
+
+Each provider adapter stays independent. Providers change on their own
+schedules, and a shared base class would couple their releases.
+
+```parallel
+Payments::*::Adapter
+```
+````
+
+A `covers` block in the primitive's `README.md` names the code that belongs to it, and a `settings` block in `duplication.md` overrides the defaults for that code:
+
+````markdown
+```covers
+Payments::*::Adapter
+views/payments/**
+```
+
+```settings
+threshold: 0.75
+min-lines: 6
+min-nodes: 30
+```
+````
+
+A clause that names code that no longer exists fails the gate, and so does a clause with nothing left to keep. The Contract stays true or the build stays red.
+
+## In CI
+
+```yaml
+exhale:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: ruby/setup-ruby@v1
+      with:
+        bundler-cache: true
+    - name: exhale
+      shell: bash
+      run: bin/exhale --base origin/${{ github.base_ref || 'main' }} | tee -a "$GITHUB_STEP_SUMMARY"
+```
+
+`fetch-depth: 0` gives exhale the history it needs to find the merge base and run `git blame`. `--format json` prints the same findings as data, and `--format edn` prints them in the shape dryer writes to `.metrics/dry.edn`.
+
+## Determinism
+
+The same commit gets the same verdict on any machine on any day. The verdict reads the commit's tree, its Contract, and the gem versions in its `Gemfile.lock`, and nothing else. Digests are unseeded, weights are fixed-point integers computed without the platform's floating-point log, and every tie breaks on a stable key.
+
+## Narrowing a run
+
+`exhale dry PATH...` reports only the findings with a location under those paths. A narrowed run still gates, on the findings inside its paths, and every path has to exist, so a typo like `exhale dyr` exits 2 instead of passing.
+
+## How exhale holds itself to this
+
+exhale has its own Contract in `contract/`: 64 numbered obligations across 11 primitives (source, unit, shape, fingerprint, matcher, sweep, gate, clause, report, revision and cli). Every obligation has at least one test that names it with a `# Contract: <primitive>/<id>` comment, and `rake contract` publishes contract coverage and fails while any obligation lacks an executable test. CI also runs exhale on itself, reading that Contract.
+
+The mutation gate runs every mutant [Mutineer](https://github.com/davidteren/mutineer) can make of `lib/` against the whole suite. Each one is either killed by a test or listed in `.mutineer.yml` with the reason no test can catch it: an equivalent mutant, an infinite loop, or a line Ruby's coverage can't see. `bin/mutate` runs it under Ruby 3.4.
+
+## Known limits in 0.1
+
+- Duplication of intent, where the same idea is written with a different structure, is out of reach for structural matching.
+- A whole method copied into another method as a nested `def` isn't reported when its body alone is under the size floors.
+- Every run sweeps the head cold and caches only the merge base. The exact incremental sweep comes in 0.2.
+- A run of statements copied more than 50 times is connected as a star from its widest copy, which can miss a near-copy that only matches another copy.
+
+## License
+
+MIT. Copyright Obie Fernandez.

data/Rakefile

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+# The Contract must be met, and contract coverage is published. Every
+# obligation in contract/*/README.md needs at least one test that names it
+# with a `# Contract: <primitive>/<id>` line, and a tag naming an obligation
+# that doesn't exist fails too, so the Contract and the tests can't drift.
+desc "Publish contract coverage and fail on any obligation without an executable test"
+task :contract do
+  obligations = Dir["contract/*/README.md"].sort.flat_map do |path|
+    primitive = File.basename(File.dirname(path))
+    File.read(path).scan(/^- \*\*([A-Z]+\d+)\*\*/).flatten.map { |id| "#{primitive}/#{id}" }
+  end
+  tags = {}
+  Dir["test/**/*_test.rb"].sort.each do |file|
+    File.foreach(file).with_index(1) do |line, number|
+      next unless (match = line.match(%r{#\s*Contract:\s*([a-z]+/[A-Z]+\d+)}))
+
+      (tags[match[1]] ||= []) << "#{file}:#{number}"
+    end
+  end
+
+  obligations.each do |id|
+    tests = tags.fetch(id, [])
+    puts "#{tests.empty? ? 'MISSING' : 'ok     '} #{id.ljust(16)} #{tests.size} test#{'s' unless tests.size == 1}"
+  end
+  covered = obligations.count { |id| tags.key?(id) }
+  puts "contract coverage: #{covered}/#{obligations.size} obligations (#{(100.0 * covered / obligations.size).round}%)"
+
+  unknown = tags.keys - obligations
+  abort "tests name obligations the Contract doesn't have: #{unknown.sort.join(', ')}" unless unknown.empty?
+  missing = obligations.reject { |id| tags.key?(id) }
+  abort "obligations with no executable test: #{missing.join(', ')}" unless missing.empty?
+end
+
+task default: %i[test contract]
+
+# Release tooling, the single-gem shape of the terret repo's rake release
+# tasks. The gemspec is the one source of name and version; nothing here
+# hardcodes either. The release workflow drives these three tasks in order.
+namespace :release do
+  gemspec = -> { Gem::Specification.load(Dir["*.gemspec"].first) }
+
+  published = lambda do |spec|
+    require "open-uri"
+    require "json"
+    body = URI.open("https://rubygems.org/api/v1/versions/#{spec.name}.json", &:read)
+    JSON.parse(body).any? { |v| v["number"] == spec.version.to_s }
+  rescue OpenURI::HTTPError
+    false # 404 => the gem has never been published, so there is nothing to skip
+  end
+
+  desc "Build the gem into pkg/ with --strict (proof the gemspec is valid). " \
+       "Reversible, pkg/ is gitignored, and the local half of a release; " \
+       "release:push is the irreversible half."
+  task :build do
+    require "fileutils"
+    spec = gemspec.call
+    FileUtils.rm_rf("pkg")
+    FileUtils.mkdir_p("pkg")
+    # --strict escalates any spec warning to a build failure.
+    sh "gem build #{File.basename(spec.loaded_from)} --strict --output pkg/#{spec.name}-#{spec.version}.gem"
+  end
+
+  desc "Print publish=true when the gemspec's version is not yet on RubyGems " \
+       "and publish=false when it is. The release workflow reads this to decide " \
+       "whether to fetch credentials and push at all."
+  task :status do
+    puts "publish=#{!published.call(gemspec.call)}"
+  end
+
+  desc "Push pkg/<gem>-<version>.gem to RubyGems. A version already published " \
+       "is skipped, so a re-run is safe. The release workflow runs this with a " \
+       "short-lived key from trusted publishing; by hand it needs RubyGems MFA."
+  task :push do
+    spec = gemspec.call
+    gem_file = "pkg/#{spec.name}-#{spec.version}.gem"
+    abort "release:push: #{gem_file} is missing, run `rake release:build` first" unless File.exist?(gem_file)
+
+    if published.call(spec)
+      puts "skip  #{spec.name} #{spec.version} (already on RubyGems)"
+      next
+    end
+
+    puts "push  #{gem_file}"
+    sh "gem push #{gem_file}"
+  end
+end

data/exe/exhale

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "exhale"
+
+exit Exhale::CLI.new(ARGV).run

data/exhale.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/exhale/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "exhale"
+  spec.version = Exhale::VERSION
+  spec.authors = ["Obie Fernandez"]
+  spec.email = ["obiefernandez@gmail.com"]
+
+  spec.summary = "The contraction gate for Rails: no PR merges while the codebase holds duplication the Contract doesn't keep"
+  spec.description = <<~DESC.strip.gsub(/\n/, " ")
+    exhale gates the exhale of every pull request in a Rails app. Its first check, exhale dry,
+    sweeps the whole codebase for duplicated Ruby and ERB, scores near-copies by rarity-weighted
+    structural similarity, and fails the build while any copy is undeclared. Deliberate
+    duplication is declared in the Contract, next to the reason for it. Built on Prism and Herb.
+  DESC
+  spec.homepage = "https://github.com/tools4imps/exhale-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.3"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ contract/ assets/ .git .github .mutineer appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = ["exhale"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "bigdecimal", "~> 3.1"
+  spec.add_dependency "herb", "~> 0.11"
+  spec.add_dependency "prism", "~> 1.9"
+
+  spec.add_development_dependency "minitest", "~> 6.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

data/lib/exhale/cli.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "version"
+require_relative "errors"
+require_relative "report"
+require_relative "dry/check"
+
+module Exhale
+  # exhale [dry] [PATH...] [options]
+  # exhale dry explain A B
+  #
+  # Exit codes: 0 pass, 1 the gate failed, 2 exhale couldn't run.
+  class CLI
+    CHECKS = %w[dry].freeze
+
+    def initialize(argv, out: $stdout, err: $stderr)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @options = { root: Dir.pwd, format: "text", include_tests: false, contract_dir: "contract",
+                   overrides: {}, introduced_only: false, base: nil, cache_dir: nil }
+    end
+
+    def run
+      @argv.shift if CHECKS.include?(@argv.first)
+      return explain(@argv.drop(1)) if @argv.first == "explain"
+
+      paths = parser.parse(@argv)
+      return 2 unless valid_format?
+
+      paths = narrowing(paths)
+      return 2 unless paths
+
+      result = Dry::Check.new(root: @options[:root], base: @options[:base], include_tests: @options[:include_tests],
+                              contract_dir: @options[:contract_dir], overrides: @options[:overrides],
+                              introduced_only: @options[:introduced_only], paths: paths,
+                              cache_dir: @options[:cache_dir]).run
+      @out.print Report.render(result, @options[:format])
+      result.exit_code
+    rescue OptionParser::ParseError, ArgumentError => e
+      @err.puts "exhale: #{e.message}"
+      @err.puts parser.banner
+      2
+    rescue Error => e
+      @err.puts "exhale: #{e.message}"
+      2
+    end
+
+    private
+
+    def parser
+      @parser ||= OptionParser.new do |o|
+        o.banner = "usage: exhale [dry] [PATH...] [options]\n       exhale dry explain IDENTITY IDENTITY"
+        o.on("--base REF", "Label findings against the merge base of REF and HEAD (default: the default branch)") do |v|
+          @options[:base] = v
+        end
+        o.on("--threshold N", Float, "Minimum score, 0 to 1 (overrides the Contract; the run won't gate)") do |v|
+          @options[:overrides][:threshold] = Rational(v.to_s)
+        end
+        o.on("--min-lines N", Integer, "Minimum source lines (overrides the Contract; the run won't gate)") do |v|
+          @options[:overrides][:min_lines] = v
+        end
+        o.on("--min-nodes N", Integer, "Minimum normalized nodes (overrides the Contract; the run won't gate)") do |v|
+          @options[:overrides][:min_nodes] = v
+        end
+        o.on("--format F", "text, json or edn (default text)") { |v| @options[:format] = v }
+        o.on("--include-tests", "Compare spec/ and test/ too") { @options[:include_tests] = true }
+        o.on("--introduced-only", "On-ramp: gate only on introduced and shifted findings") do
+          @options[:introduced_only] = true
+        end
+        o.on("--contract DIR", "The Contract's root (default contract/)") { |v| @options[:contract_dir] = v }
+        o.on("--cache DIR", "Cache directory (default tmp/exhale/)") { |v| @options[:cache_dir] = v }
+        o.on("--root DIR", "Repository root (default: the current directory)") { |v| @options[:root] = v }
+        o.on("-v", "--version", "Print the version") do
+          @out.puts "exhale #{VERSION}"
+          exit 0
+        end
+        o.on("-h", "--help", "Print this help") do
+          @out.puts o
+          exit 0
+        end
+      end
+    end
+
+    # Every positional argument has to be a path that exists under the root.
+    # A typo like `exhale dyr` must fail loudly, never narrow the run to
+    # nothing and pass.
+    def narrowing(args)
+      root = File.expand_path(@options[:root])
+      args.map do |arg|
+        full = File.expand_path(arg, root)
+        unless File.exist?(full) && (full == root || full.start_with?("#{root}/"))
+          @err.puts "exhale: #{arg.inspect} is neither a command nor a path under #{root}"
+          return nil
+        end
+        full == root ? "." : full.delete_prefix("#{root}/")
+      end
+    end
+
+    def valid_format?
+      return true if Report::FORMATS.include?(@options[:format])
+
+      @err.puts "exhale: unknown format #{@options[:format].inspect} (use text, json or edn)"
+      false
+    end
+
+    # Prints two units' normalized trees and their score, for tuning. It
+    # checks --format, --root and --base the way a run does, so a flag that
+    # would fail CI fails here too.
+    def explain(args)
+      args = parser.parse(args)
+      unless args.size == 2
+        @err.puts "usage: exhale dry explain IDENTITY IDENTITY"
+        return 2
+      end
+      return 2 unless valid_format?
+
+      Dry::Check.new(root: @options[:root], base: @options[:base], cache_dir: @options[:cache_dir]).validate!
+      root = File.expand_path(@options[:root])
+      git = Git.new(root)
+      sweep = Dry::Sweep.new(root, files: (git.files if git.repo?), include_tests: @options[:include_tests],
+                                   contract_dir: @options[:contract_dir]).run
+      a, b = args.map { |identity| sweep.index.entries.find { |e| e.unit.identity == identity } }
+      missing = args.zip([a, b]).find { |_, entry| entry.nil? }
+      if missing
+        @err.puts "exhale: no unit named #{missing[0]}"
+        return 2
+      end
+
+      [a, b].each do |entry|
+        @out.puts "#{entry.unit.identity}  #{entry.unit.path}:#{entry.unit.start_line}-#{entry.unit.end_line}"
+        print_shape(Dry::Normalizer.normalize(entry.unit), 1)
+        @out.puts
+      end
+      shared = a.set & b.set
+      @out.puts "score #{Report.score(sweep.index.score(a.set, a.total, b.set, b.total))}, " \
+                "#{shared.size} shared of #{(a.set | b.set).size} fingerprints"
+      0
+    end
+
+    def print_shape(shape, depth)
+      label = shape.label ? " #{shape.label}" : ""
+      @out.puts "#{'  ' * depth}#{shape.kind}#{label}"
+      shape.children.each { |child| print_shape(child, depth + 1) }
+    end
+  end
+end

data/lib/exhale/contract/markdown.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Exhale
+  class Contract
+    # A line scanner for the little Markdown the Contract needs: fenced blocks
+    # (CommonMark fence rules), the nearest ATX heading above each, and the
+    # prose between that heading and the block. No Markdown gem.
+    module Markdown
+      Block = Struct.new(:info, :line, :body, :heading, :prose, keyword_init: true) do
+        # body is [[text, line_number], ...]
+        def reason
+          [heading, *prose].compact.join(" ").gsub(/\s+/, " ").strip
+        end
+      end
+
+      FENCE_OPEN = /\A {0,3}(`{3,}|~{3,})(.*)\z/
+      HEADING = /\A {0,3}\#{1,6}(?:[ \t]+(.*))?\z/
+
+      module_function
+
+      def blocks(text)
+        state = { blocks: [], heading: nil, prose: [], fence: nil, comment: false }
+        text.each_line.with_index(1) { |raw, no| step(state, raw.chomp, no) }
+        state[:blocks] << finish(state[:fence]) if state[:fence]
+        state[:blocks]
+      end
+
+      SETEXT = /\A {0,3}(?:=+|-+)[ \t]*\z/
+
+      def step(state, line, no)
+        after_prose = state[:after_prose]
+        state[:after_prose] = false
+        fence = state[:fence]
+        if fence
+          continue_fence(state, fence, line, no)
+        elsif (line = outside_comments(state, line)).nil?
+          nil
+        elsif (fence = open_fence(line, no, state))
+          state[:fence] = fence
+        elsif after_prose && SETEXT.match?(line)
+          state[:heading] = state[:prose].pop
+          state[:prose] = []
+        elsif (m = HEADING.match(line))
+          state[:heading] = m[1].to_s.sub(/[ \t]+#+[ \t]*\z/, "").sub(/\A#+\z/, "").strip
+          state[:prose] = []
+        elsif !line.strip.empty?
+          state[:prose] << line.strip
+          state[:after_prose] = true
+        end
+      end
+
+      # Returns the part of the line that is live Markdown, or nil when the
+      # whole line sits inside an HTML comment. Fences in comments are dead.
+      def outside_comments(state, line)
+        if state[:comment]
+          return nil unless line.include?("-->")
+
+          state[:comment] = false
+          line = line.sub(/\A.*?-->/, "")
+        end
+        line = line.gsub(/<!--.*?-->/, "")
+        return line unless line.include?("<!--")
+
+        state[:comment] = true
+        line.sub(/<!--.*\z/, "")
+      end
+
+      def continue_fence(state, fence, line, no)
+        if closes?(line, fence)
+          state[:blocks] << finish(fence)
+          state[:fence] = nil
+          state[:prose] = [] if %w[parallel settings covers].include?(fence[:info])
+        else
+          fence[:body] << [line, no]
+        end
+      end
+
+      def open_fence(line, no, state)
+        m = FENCE_OPEN.match(line)
+        return nil unless m
+        return nil if m[1].start_with?("`") && m[2].include?("`")
+
+        { char: m[1][0], len: m[1].size, info: m[2].strip.split(/\s+/).first.to_s, line: no, body: [],
+          heading: state[:heading], prose: state[:prose].dup }
+      end
+
+      def closes?(line, fence)
+        m = /\A {0,3}(`{3,}|~{3,})[ \t]*\z/.match(line)
+        m && m[1][0] == fence[:char] && m[1].size >= fence[:len]
+      end
+
+      def finish(fence)
+        Block.new(info: fence[:info], line: fence[:line], body: fence[:body],
+                  heading: fence[:heading], prose: fence[:prose])
+      end
+
+      # Drops a trailing comment: "#" preceded by whitespace and followed by a
+      # space or end of line. A "#" glued to a name is part of a method ref.
+      def strip_comment(line)
+        stripped = line.strip
+        return "" if stripped.match?(/\A#(\s|\z)/)
+
+        stripped.sub(/\s+#(\s.*)?\z/, "")
+      end
+    end
+  end
+end

data/lib/exhale/contract/reference.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Exhale
+  class Contract
+    # A line from a covers or parallel block, with where it was written.
+    Reference = Struct.new(:text, :path, :line) do
+      def kind
+        if text.include?("/") then :template_glob
+        elsif text.match?(/[#.]/) then :method
+        elsif text.include?("*") then :const_glob
+        else :constant
+        end
+      end
+
+      # Orders references by how narrowly they point: method refs first, then
+      # more literal segments, more segments, fewer "**", longer text.
+      def specificity
+        return [1, 0, 0, 0, text.length] if kind == :method
+
+        segs = kind == :template_glob ? text.split("/") : const_segments
+        [0, segs.count { |s| !s.include?("*") }, segs.size, -segs.count("**"), text.length]
+      end
+
+      def const_segments
+        text.split("::")
+      end
+
+      def template_regex
+        pieces = text.split(%r{(/\*\*/|\*\*/|/\*\*\z|\*\*|\*)})
+        body = pieces.map { |p| TEMPLATE_TOKENS.fetch(p) { Regexp.escape(p) } }.join
+        Regexp.new("\\A#{body}\\z")
+      end
+
+      TEMPLATE_TOKENS = {
+        "/**/" => "/(?:.*/)?", "**/" => "(?:.*/)?", "/**" => "/.*", "**" => ".*", "*" => "[^/]*"
+      }.freeze
+
+      # Does a namespace prefix (an Array of segments) match this constant glob?
+      def const_glob_match?(segments)
+        self.class.seg_match?(const_segments, segments)
+      end
+
+      # Bottom-up DP over (pattern index, segment index): O(patterns * segments)
+      # however many "**" the pattern holds.
+      def self.seg_match?(pats, segs)
+        np = pats.size
+        ns = segs.size
+        # ok[j]: pats[i..] matches segs[j..], built for i from np down to 0.
+        ok = Array.new(ns + 1) { |j| j == ns }
+        (np - 1).downto(0) do |i|
+          nxt = ok
+          ok = Array.new(ns + 1, false)
+          if pats[i] == "**"
+            ns.downto(0) { |j| ok[j] = nxt[j] || (j < ns && ok[j + 1]) }
+          else
+            ns.times { |j| ok[j] = nxt[j + 1] && File.fnmatch?(pats[i], segs[j]) }
+          end
+        end
+        ok[0]
+      end
+    end
+  end
+end