yarn_skein 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4fdd27e3f715f8b7f200f6bd5f604e503dad0bb61cb2d0f8cd0100680c902e77
-  data.tar.gz: 0a121d542d7559e6a5b1c6ef36df30f0a7676c0b64f25c3194eaf90124c8cf7b
+  metadata.gz: 2efd2c01dfa8a4654b1f110487399eb0111dba77daf030e7d3826d3514531a75
+  data.tar.gz: ea44d7874a49e18995a51e9ca09a04c787bf43db2f49a79281213f4679db14bb
 SHA512:
-  metadata.gz: 2a0f0c9d824f8689a18265c0d20dde24267649a4ff2f0d174330dff7f0de0e9e60575075d9f25fe32865fa3c9530f206c2f72652afbad050bb5070ce3f28ed10
-  data.tar.gz: 76e392350e32d039c950b9b9680b027e2554982335e8b2c01abe2f76f30e29dae1dca3630b4316411e41eff25d28659591f7fb573f6932505036e6e05c2a2925
+  metadata.gz: 737cb9cedba8020ac8d5050d771a3051f43fa56a1a55c634120dbb77d1a977e22e0affb71d5b4746fa106c488468a19a737a4723319eb71e85a06722ab2d07fa
+  data.tar.gz: e52704d9b994e919071302371e97c0d7d56fe0b72e64c26c01d71015211e520566a6406d1de8c259c5826b10614d2a748c69d0852f9f62c09c275c2a50c23a76

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-26
+
+### Added
+- `YarnSkein::Catalog` for loading yarn data from YAML seed files with filtering by brand, weight category, and fiber content
+- `YarnSkein::YardageEstimator` for estimating total yarn yardage from gauge and dimensions
+- Rectangular piece estimation via `for_rectangle(width:, height:)`
+- Stitch/row count estimation via `for_piece(stitches:, rows:)`
+- Configurable safety margin (default 10%) for waste and joining
+- Added `fiber_gauge` as a runtime dependency
+
+## [0.2.0] - 2026-03-21
+
+### Added
+- `YarnSkein::Substitution` for finding compatible yarn substitutes from a catalog
+- Matches by weight category and grist tolerance (default 15%, configurable)
+- Optional fiber content filter
+- Added missing `rake` and `simplecov-json` dev dependencies
 
 ## [0.1.1] - 2026-03-14
 ### Added

data/Rakefile

@@ -1,58 +1,10 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-require "yard"
-require "yard/rake/yardoc_task"
-require "standard/rake"
+require "rake/testtask"
 
-# YARD Documentation tasks
-begin
-  namespace :doc do
-    desc "Generate YARD documentation"
-    YARD::Rake::YardocTask.new(:generate) do |t|
-      t.files = ["lib/**/*.rb", "-", "README.md"]
-      t.options = [
-        "--output-dir", "doc/yard",
-        "--markup", "markdown",
-        "--title", "YarnSkein - Yarn metadata and skein calculations",
-        "--readme", "README.md"
-      ]
-    end
-
-    desc "Regenerate documentation with cache reset"
-    task regenerate: ["doc:clean", "doc:generate"]
-
-    desc "Clean generated documentation"
-    task :clean do
-      rm_rf "doc/yard"
-      rm_rf ".yardoc"
-    end
-
-    desc "Start YARD server for local documentation viewing"
-    task :serve do
-      sh "bundle exec yard server --reload --port 8808"
-    end
-
-    desc "Validate YARD documentation coverage"
-    task :coverage do
-      sh "bundle exec yard stats --list-undoc"
-    end
-
-    desc "Generate complete documentation with coverage report"
-    task complete: [:generate, :coverage]
-  end
-
-  # Add shorthand aliases
-  task yard: "doc:generate"
-  task yard_server: "doc:serve"
-  task yard_clean: "doc:clean"
-rescue LoadError
-  # YARD is only available in development/test environments
-  # Silence this warning in production where it's not needed
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
 end
 
-task :default do
-  Rake::Task["standard"].invoke
-  Rake::Task["spec"].invoke
-end
+task default: :test

data/lib/yarn_skein/catalog.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module YarnSkein
+  class Catalog
+    def initialize(data_dir: nil)
+      @data_dir = data_dir || default_data_dir
+      @yarns = nil
+    end
+
+    def all
+      load_yarns
+    end
+
+    def filter(brand: nil, weight_category: nil, fiber: nil)
+      results = all
+      results = results.select { |y| y.brand.downcase == brand.downcase } if brand
+      results = results.select { |y| y.weight_category == weight_category.to_sym } if weight_category
+      results = results.select { |y| y.fiber_content&.contains?(fiber.to_sym) } if fiber
+      results
+    end
+
+    def brands
+      all.map(&:brand).uniq.sort
+    end
+
+    def find(brand:, line:)
+      all.detect { |y| y.brand.downcase == brand.downcase && y.line.downcase == line.downcase }
+    end
+
+    private
+
+    def load_yarns
+      @yarns ||= Dir.glob(File.join(@data_dir, "*.yml")).reject { |f| File.basename(f).start_with?("_") }.flat_map { |file| parse_brand_file(file) }
+    end
+
+    def parse_brand_file(file)
+      data = YAML.safe_load_file(file, permitted_classes: [])
+      brand_name = data["brand"]
+      (data["yarns"] || []).filter_map do |entry|
+        build_yarn(brand_name, entry)
+      end
+    end
+
+    def build_yarn(brand_name, entry)
+      yardage = entry["yardage"]
+      skein_weight = entry["skein_weight"]
+      return nil unless yardage && skein_weight
+
+      fiber_content = nil
+      if entry["fiber_content"] && !entry["fiber_content"].empty?
+        fiber_hash = entry["fiber_content"].transform_keys(&:to_sym).transform_values(&:to_i)
+        fiber_content = FiberBlend.new(fiber_hash)
+      end
+
+      Yarn.new(
+        brand: brand_name,
+        line: entry["line"],
+        yardage: yardage.to_f.yards,
+        skein_weight: skein_weight.to_f.grams,
+        fiber_content: fiber_content
+      )
+    end
+
+    def default_data_dir
+      env_path = ENV["YARN_CATALOG_PATH"]
+      return env_path if env_path
+
+      File.expand_path("../../../../data/yarns", __dir__)
+    end
+  end
+end

data/lib/yarn_skein/substitution.rb

@@ -0,0 +1,30 @@
+module YarnSkein
+  class Substitution
+    DEFAULT_TOLERANCE = 0.15
+
+    attr_reader :target, :catalog
+
+    def initialize(target:, catalog:)
+      @target = target
+      @catalog = catalog
+    end
+
+    def matches(tolerance: DEFAULT_TOLERANCE, fiber: nil)
+      catalog.select do |yarn|
+        next false if yarn == target
+        next false unless yarn.weight_category == target.weight_category
+        next false unless within_grist_tolerance?(yarn, tolerance)
+        next false if fiber && !yarn.fiber_content&.contains?(fiber)
+
+        true
+      end
+    end
+
+    private
+
+    def within_grist_tolerance?(yarn, tolerance)
+      ratio = yarn.yards_per_100g / target.yards_per_100g.to_f
+      ratio.between?(1.0 - tolerance, 1.0 + tolerance)
+    end
+  end
+end

data/lib/yarn_skein/version.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+# :nocov:
 module YarnSkein
   # Current gem version.
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end
+# :nocov:

data/lib/yarn_skein/yardage_estimator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module YarnSkein
+  # Estimates total yarn yardage required for a project based on gauge and yarn.
+  #
+  # Uses a geometric stitch model: each knit stitch consumes approximately
+  # one stitch-width plus two stitch-heights of yarn (the U-shaped loop path).
+  # This gives a reasonable estimate for stockinette and similar stitch patterns.
+  #
+  # @example
+  #   estimator = YarnSkein::YardageEstimator.new(gauge: gauge, yarn: yarn)
+  #   estimator.for_rectangle(width: 60.inches, height: 72.inches)
+  #   # => { yardage: <FiberUnits::Length>, skeins: 10 }
+  class YardageEstimator
+    # Default safety margin added to yardage estimates (10%).
+    DEFAULT_MARGIN = 0.10
+
+    # @return [FiberGauge::Gauge] gauge used for stitch/row calculations
+    attr_reader :gauge
+
+    # @return [YarnSkein::Yarn] yarn used for skein calculations
+    attr_reader :yarn
+
+    # @param gauge [FiberGauge::Gauge] gauge swatch data
+    # @param yarn [YarnSkein::Yarn] yarn being used
+    def initialize(gauge:, yarn:)
+      @gauge = gauge
+      @yarn = yarn
+    end
+
+    # Estimates yardage for a rectangular piece (scarf, blanket, etc.).
+    #
+    # @param width [FiberUnits::Length] finished width
+    # @param height [FiberUnits::Length] finished height
+    # @param margin [Float] safety margin as a decimal (default 0.10 = 10%)
+    # @return [Hash] :yardage [FiberUnits::Length] and :skeins [Integer]
+    def for_rectangle(width:, height:, margin: DEFAULT_MARGIN)
+      stitches = gauge.required_stitches(width)
+      rows = gauge.required_rows(height)
+
+      for_piece(stitches: stitches, rows: rows, margin: margin)
+    end
+
+    # Estimates yardage from stitch and row counts directly.
+    #
+    # @param stitches [FiberUnits::StitchCount] total stitches across
+    # @param rows [FiberUnits::RowCount] total rows
+    # @param margin [Float] safety margin as a decimal (default 0.10 = 10%)
+    # @return [Hash] :yardage [FiberUnits::Length] and :skeins [Integer]
+    def for_piece(stitches:, rows:, margin: DEFAULT_MARGIN)
+      total_stitches = stitches.value * rows.value
+      yardage = (total_stitches * yards_per_stitch * (1.0 + margin)).yards
+
+      {yardage: yardage, skeins: yarn.skeins_required(yardage)}
+    end
+
+    # Returns the estimated yards of yarn consumed per stitch.
+    #
+    # Models each stitch as a U-shaped loop: one stitch-width across plus
+    # two stitch-heights for the legs of the loop.
+    #
+    # @return [Float] yards per stitch
+    def yards_per_stitch
+      stitch_width_in = 1.0 / gauge.spi
+      stitch_height_in = 1.0 / gauge.rpi
+      yarn_per_stitch_in = stitch_width_in + (2.0 * stitch_height_in)
+
+      yarn_per_stitch_in / 36.0
+    end
+  end
+end

data/lib/yarn_skein.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 require "fiber_units"
+require "fiber_gauge"
 require_relative "yarn_skein/version"
 require_relative "yarn_skein/weight_category"
 require_relative "yarn_skein/fiber_blend"
 require_relative "yarn_skein/yarn"
+require_relative "yarn_skein/substitution"
+require_relative "yarn_skein/yardage_estimator"
+require_relative "yarn_skein/catalog"
 
 # Domain objects for describing yarn skeins, fiber blends, and weight classes.
 #

data/test/catalog_test.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "tmpdir"
+require "yaml"
+require "fileutils"
+
+class CatalogTest < Minitest::Test
+  def setup
+    @data_dir = Dir.mktmpdir("catalog_test")
+    write_fixture("malabrigo.yml", {
+      "brand" => "Malabrigo",
+      "slug" => "malabrigo",
+      "yarns" => [
+        {
+          "line" => "Rios",
+          "slug" => "rios",
+          "weight_category" => "worsted",
+          "yardage" => 210,
+          "skein_weight" => 100,
+          "fiber_content" => {"wool" => 100},
+          "colorways" => []
+        },
+        {
+          "line" => "Mechita",
+          "slug" => "mechita",
+          "weight_category" => "fingering",
+          "yardage" => 420,
+          "skein_weight" => 100,
+          "fiber_content" => {"wool" => 100},
+          "colorways" => []
+        }
+      ]
+    })
+
+    write_fixture("cascade.yml", {
+      "brand" => "Cascade",
+      "slug" => "cascade",
+      "yarns" => [
+        {
+          "line" => "220 Superwash",
+          "slug" => "220-superwash",
+          "weight_category" => "worsted",
+          "yardage" => 200,
+          "skein_weight" => 100,
+          "fiber_content" => {"wool" => 100},
+          "colorways" => []
+        }
+      ]
+    })
+
+    # Meta file should be ignored
+    write_fixture("_meta.yml", {"scraped_at" => "2026-01-01", "version" => "1.0"})
+  end
+
+  def teardown
+    FileUtils.rm_rf(@data_dir)
+  end
+
+  # ---- all ----
+
+  def test_all_returns_yarn_objects
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    yarns = catalog.all
+
+    assert_equal 3, yarns.size
+    assert yarns.all? { |y| y.is_a?(YarnSkein::Yarn) }
+  end
+
+  def test_all_skips_meta_files
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    brands = catalog.all.map(&:brand).uniq
+
+    refute_includes brands, "scraped_at"
+  end
+
+  # ---- filter ----
+
+  def test_filter_by_brand
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(brand: "Malabrigo")
+
+    assert_equal 2, results.size
+    assert results.all? { |y| y.brand == "Malabrigo" }
+  end
+
+  def test_filter_by_weight_category
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(weight_category: :worsted)
+
+    assert_equal 2, results.size
+    assert results.all? { |y| y.weight_category == :worsted }
+  end
+
+  def test_filter_by_fiber
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(fiber: :wool)
+
+    assert_equal 3, results.size
+  end
+
+  def test_filter_combined
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(brand: "Malabrigo", weight_category: :worsted)
+
+    assert_equal 1, results.size
+    assert_equal "Rios", results.first.line
+  end
+
+  # ---- brands ----
+
+  def test_brands_returns_unique_sorted_list
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+
+    assert_equal ["Cascade", "Malabrigo"], catalog.brands
+  end
+
+  # ---- find ----
+
+  def test_find_returns_matching_yarn
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    yarn = catalog.find(brand: "Malabrigo", line: "Rios")
+
+    assert_equal "Malabrigo", yarn.brand
+    assert_equal "Rios", yarn.line
+  end
+
+  def test_find_is_case_insensitive
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    yarn = catalog.find(brand: "malabrigo", line: "rios")
+
+    assert_equal "Malabrigo", yarn.brand
+  end
+
+  def test_find_returns_nil_when_not_found
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+
+    assert_nil catalog.find(brand: "Unknown", line: "Yarn")
+  end
+
+  # ---- empty directory ----
+
+  def test_empty_data_dir
+    empty_dir = Dir.mktmpdir("empty_catalog")
+    catalog = YarnSkein::Catalog.new(data_dir: empty_dir)
+
+    assert_empty catalog.all
+    assert_empty catalog.brands
+  ensure
+    FileUtils.rm_rf(empty_dir)
+  end
+
+  # ---- skips entries without yardage ----
+
+  def test_skips_entries_missing_yardage
+    dir = Dir.mktmpdir("incomplete_catalog")
+    write_fixture_to(dir, "incomplete.yml", {
+      "brand" => "Incomplete",
+      "slug" => "incomplete",
+      "yarns" => [
+        {"line" => "NoYardage", "slug" => "no-yardage", "skein_weight" => 100, "fiber_content" => {}},
+        {"line" => "Valid", "slug" => "valid", "yardage" => 200, "skein_weight" => 100, "fiber_content" => {"wool" => 100}}
+      ]
+    })
+
+    catalog = YarnSkein::Catalog.new(data_dir: dir)
+    assert_equal 1, catalog.all.size
+    assert_equal "Valid", catalog.all.first.line
+  ensure
+    FileUtils.rm_rf(dir)
+  end
+
+  private
+
+  def write_fixture(filename, data)
+    write_fixture_to(@data_dir, filename, data)
+  end
+
+  def write_fixture_to(dir, filename, data)
+    File.write(File.join(dir, filename), YAML.dump(data))
+  end
+end

data/test/fiber_blend_test.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class YarnSkeinFiberBlendTest < Minitest::Test
+  # -----------------------------
+  # Initialization
+  # -----------------------------
+
+  def test_stores_fiber_percentages
+    blend = YarnSkein::FiberBlend.new(
+      merino_wool: 80,
+      nylon: 20
+    )
+
+    assert_equal(
+      {
+        merino_wool: 80,
+        nylon: 20
+      },
+      blend.fibers
+    )
+  end
+
+  def test_raises_error_if_percentages_do_not_sum_to_100
+    error = assert_raises(ArgumentError) do
+      YarnSkein::FiberBlend.new(
+        merino_wool: 50,
+        nylon: 30
+      )
+    end
+
+    assert_match(/must sum to 100/, error.message)
+  end
+
+  # -----------------------------
+  # yards_per_100g
+  # -----------------------------
+
+  def test_calculates_yards_per_100_grams
+    yarn = YarnSkein::Yarn.new(
+      brand: "Malabrigo",
+      line: "Rios",
+      yardage: 210.yards,
+      skein_weight: 100.grams
+    )
+
+    assert_equal 210, yarn.yards_per_100g
+  end
+
+  # -----------------------------
+  # percentage
+  # -----------------------------
+
+  def test_returns_percentage_of_fiber
+    blend = YarnSkein::FiberBlend.new(
+      merino_wool: 80,
+      nylon: 20
+    )
+
+    assert_equal 80, blend.percentage(:merino_wool)
+  end
+
+  def test_returns_zero_for_missing_fibers
+    blend = YarnSkein::FiberBlend.new(
+      merino_wool: 100
+    )
+
+    assert_equal 0, blend.percentage(:nylon)
+  end
+
+  # -----------------------------
+  # contains?
+  # -----------------------------
+
+  def test_contains_returns_true_if_fiber_exists
+    blend = YarnSkein::FiberBlend.new(
+      merino_wool: 80,
+      nylon: 20
+    )
+
+    assert blend.contains?(:nylon)
+  end
+
+  def test_contains_returns_false_if_fiber_does_not_exist
+    blend = YarnSkein::FiberBlend.new(
+      merino_wool: 100
+    )
+
+    refute blend.contains?(:nylon)
+  end
+end

data/test/substitution_test.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class YarnSkeinSubstitutionTest < Minitest::Test
+  def build_yarn(line:, yardage:, skein_weight:, fiber_content: nil)
+    YarnSkein::Yarn.new(
+      brand: "TestBrand",
+      line: line,
+      yardage: yardage,
+      skein_weight: skein_weight,
+      fiber_content: fiber_content
+    )
+  end
+
+  def target_yarn
+    @target_yarn ||= build_yarn(line: "Target", yardage: 210.yards, skein_weight: 100.grams)
+  end
+
+  # 210 yards/100g => worsted, yards_per_100g = 210
+
+  def close_match
+    @close_match ||= build_yarn(line: "Close", yardage: 200.yards, skein_weight: 100.grams)
+  end
+
+  def exact_match
+    @exact_match ||= build_yarn(line: "Exact", yardage: 210.yards, skein_weight: 100.grams)
+  end
+
+  def too_far
+    @too_far ||= build_yarn(line: "TooFar", yardage: 300.yards, skein_weight: 100.grams)
+  end
+
+  def different_category
+    @different_category ||= build_yarn(line: "Bulky", yardage: 120.yards, skein_weight: 100.grams)
+  end
+
+  def wool_yarn
+    @wool_yarn ||= build_yarn(
+      line: "Wool",
+      yardage: 200.yards,
+      skein_weight: 100.grams,
+      fiber_content: YarnSkein::FiberBlend.new(wool: 100)
+    )
+  end
+
+  def cotton_yarn
+    @cotton_yarn ||= build_yarn(
+      line: "Cotton",
+      yardage: 200.yards,
+      skein_weight: 100.grams,
+      fiber_content: YarnSkein::FiberBlend.new(cotton: 100)
+    )
+  end
+
+  # -----------------------------
+  # matches
+  # -----------------------------
+
+  def test_returns_yarns_matching_weight_category_and_grist
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [close_match, too_far])
+
+    assert_equal [close_match], sub.matches
+  end
+
+  def test_excludes_target_yarn_from_results
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [target_yarn, close_match])
+
+    assert_equal [close_match], sub.matches
+  end
+
+  def test_excludes_different_weight_category
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [different_category])
+
+    assert_empty sub.matches
+  end
+
+  def test_returns_empty_for_empty_catalog
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [])
+
+    assert_empty sub.matches
+  end
+
+  def test_returns_empty_when_no_matches
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [too_far, different_category])
+
+    assert_empty sub.matches
+  end
+
+  # -----------------------------
+  # tolerance
+  # -----------------------------
+
+  def test_configurable_tolerance
+    # close_match is 200/210 = ~0.952, within 15% but outside 2%
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [close_match])
+
+    assert_equal [close_match], sub.matches(tolerance: 0.15)
+    assert_empty sub.matches(tolerance: 0.02)
+  end
+
+  # -----------------------------
+  # fiber filter
+  # -----------------------------
+
+  def test_filters_by_fiber_content
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [wool_yarn, cotton_yarn])
+
+    assert_equal [wool_yarn], sub.matches(fiber: :wool)
+  end
+
+  def test_fiber_filter_excludes_yarns_without_fiber_content
+    yarn_no_fiber = build_yarn(line: "NoFiber", yardage: 200.yards, skein_weight: 100.grams)
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [yarn_no_fiber, wool_yarn])
+
+    assert_equal [wool_yarn], sub.matches(fiber: :wool)
+  end
+
+  def test_includes_exact_grist_match
+    sub = YarnSkein::Substitution.new(target: target_yarn, catalog: [exact_match])
+
+    assert_equal [exact_match], sub.matches
+  end
+end