yarn_skein 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de030bc1badf27891aebbba5deb39a73ab035fbe4be31842f4e9d2bb8105ecdb
-  data.tar.gz: 9ae3781907723962ea50c3b25a3f98705c321f251f981a6a558b3a81218ed442
+  metadata.gz: 2efd2c01dfa8a4654b1f110487399eb0111dba77daf030e7d3826d3514531a75
+  data.tar.gz: ea44d7874a49e18995a51e9ca09a04c787bf43db2f49a79281213f4679db14bb
 SHA512:
-  metadata.gz: 5c4bbcb7d360334e2f79d733f4d53d2371414f2c6e73bc48b67d1a3e027e2c48a1e822d56fbc424ef6c42dfacbbcd471f00ab55497baac641ea510f4564748a0
-  data.tar.gz: cc0e8ac28ad96f6977471b3fca483989ca8b0e2142040dce66632714c0c3b022d972ec363f395af645f4143a41757357bf48ef362833a399a183d08a0093b708
+  metadata.gz: 737cb9cedba8020ac8d5050d771a3051f43fa56a1a55c634120dbb77d1a977e22e0affb71d5b4746fa106c488468a19a737a4723319eb71e85a06722ab2d07fa
+  data.tar.gz: e52704d9b994e919071302371e97c0d7d56fe0b72e64c26c01d71015211e520566a6406d1de8c259c5826b10614d2a748c69d0852f9f62c09c275c2a50c23a76

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [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
 

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/version.rb

@@ -3,6 +3,6 @@
 # :nocov:
 module YarnSkein
   # Current gem version.
-  VERSION = "0.2.0"
+  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,11 +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/yardage_estimator_test.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class YarnSkeinYardageEstimatorTest < Minitest::Test
+  def gauge
+    FiberGauge::Gauge.new(
+      stitches: 18.stitches,
+      rows: 24.rows,
+      width: 4.inches,
+      height: 4.inches
+    )
+  end
+
+  def yarn
+    YarnSkein::Yarn.new(
+      brand: "Malabrigo",
+      line: "Rios",
+      yardage: 210.yards,
+      skein_weight: 100.grams
+    )
+  end
+
+  def estimator
+    YarnSkein::YardageEstimator.new(gauge: gauge, yarn: yarn)
+  end
+
+  # -----------------------------
+  # yards_per_stitch
+  # -----------------------------
+
+  def test_yards_per_stitch_returns_positive_value
+    assert estimator.yards_per_stitch > 0
+  end
+
+  def test_yards_per_stitch_uses_geometric_model
+    spi = gauge.spi
+    rpi = gauge.rpi
+    expected = (1.0 / spi + 2.0 / rpi) / 36.0
+
+    assert_in_delta expected, estimator.yards_per_stitch, 0.0001
+  end
+
+  # -----------------------------
+  # for_piece
+  # -----------------------------
+
+  def test_for_piece_returns_yardage_and_skeins
+    result = estimator.for_piece(stitches: 100.stitches, rows: 100.rows)
+
+    assert result.key?(:yardage)
+    assert result.key?(:skeins)
+    assert_instance_of FiberUnits::Length, result[:yardage]
+    assert_instance_of Integer, result[:skeins]
+  end
+
+  def test_for_piece_yardage_is_positive
+    result = estimator.for_piece(stitches: 100.stitches, rows: 100.rows)
+
+    assert result[:yardage].value > 0
+  end
+
+  def test_for_piece_includes_default_margin
+    no_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.0)
+    with_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows)
+
+    assert_in_delta(
+      no_margin[:yardage].to(:yards).value * 1.10,
+      with_margin[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  def test_for_piece_custom_margin
+    no_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.0)
+    with_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.20)
+
+    assert_in_delta(
+      no_margin[:yardage].to(:yards).value * 1.20,
+      with_margin[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  def test_for_piece_zero_margin
+    result = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.0)
+
+    total_ops = 100 * 100
+    expected_yards = total_ops * estimator.yards_per_stitch
+
+    assert_in_delta expected_yards, result[:yardage].to(:yards).value, 0.01
+  end
+
+  def test_for_piece_skeins_ceil_to_whole_number
+    result = estimator.for_piece(stitches: 50.stitches, rows: 50.rows, margin: 0.0)
+
+    raw_yards = 50 * 50 * estimator.yards_per_stitch
+    expected_skeins = (raw_yards / 210.0).ceil
+
+    assert_equal expected_skeins, result[:skeins]
+  end
+
+  # -----------------------------
+  # for_rectangle
+  # -----------------------------
+
+  def test_for_rectangle_returns_yardage_and_skeins
+    result = estimator.for_rectangle(width: 20.inches, height: 30.inches)
+
+    assert result.key?(:yardage)
+    assert result.key?(:skeins)
+  end
+
+  def test_for_rectangle_uses_gauge_to_compute_stitches
+    rect_result = estimator.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.0)
+
+    stitches = gauge.required_stitches(20.inches)
+    rows = gauge.required_rows(30.inches)
+    piece_result = estimator.for_piece(stitches: stitches, rows: rows, margin: 0.0)
+
+    assert_in_delta(
+      piece_result[:yardage].to(:yards).value,
+      rect_result[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  def test_for_rectangle_with_custom_margin
+    no_margin = estimator.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.0)
+    with_margin = estimator.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.15)
+
+    assert_in_delta(
+      no_margin[:yardage].to(:yards).value * 1.15,
+      with_margin[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  # -----------------------------
+  # realistic scenarios
+  # -----------------------------
+
+  def test_scarf_estimate_is_reasonable
+    # A scarf ~8" wide, 60" long in worsted weight
+    result = estimator.for_rectangle(width: 8.inches, height: 60.inches)
+
+    yards = result[:yardage].to(:yards).value
+    # A worsted scarf typically uses 200-400 yards
+    assert yards > 100, "yardage #{yards} seems too low for a scarf"
+    assert yards < 600, "yardage #{yards} seems too high for a scarf"
+  end
+
+  def test_blanket_estimate_is_reasonable
+    # A throw blanket ~50" x 60" in worsted weight
+    result = estimator.for_rectangle(width: 50.inches, height: 60.inches)
+
+    yards = result[:yardage].to(:yards).value
+    # A worsted throw typically uses 1500-3500 yards
+    assert yards > 1000, "yardage #{yards} seems too low for a blanket"
+    assert yards < 5000, "yardage #{yards} seems too high for a blanket"
+  end
+
+  def test_larger_piece_needs_more_yarn
+    small = estimator.for_rectangle(width: 10.inches, height: 10.inches)
+    large = estimator.for_rectangle(width: 20.inches, height: 20.inches)
+
+    assert large[:yardage].to(:yards).value > small[:yardage].to(:yards).value
+    assert large[:skeins] >= small[:skeins]
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yarn_skein
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Meagan Waller
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: fiber_gauge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -51,25 +65,29 @@ files:
 - README.md
 - Rakefile
 - lib/yarn_skein.rb
+- lib/yarn_skein/catalog.rb
 - lib/yarn_skein/fiber_blend.rb
 - lib/yarn_skein/substitution.rb
 - lib/yarn_skein/version.rb
 - lib/yarn_skein/weight_category.rb
+- lib/yarn_skein/yardage_estimator.rb
 - lib/yarn_skein/yarn.rb
 - sig/yarn_skein.rbs
+- test/catalog_test.rb
 - test/fiber_blend_test.rb
 - test/substitution_test.rb
 - test/test_helper.rb
 - test/version_test.rb
 - test/weight_category_test.rb
+- test/yardage_estimator_test.rb
 - test/yarn_test.rb
-homepage: https://github.com/meaganewaller/yarn_skein
+homepage: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/meaganewaller/yarn_skein
-  source_code_uri: https://github.com/meaganewaller/yarn_skein
-  changelog_uri: https://github.com/meaganewaller/yarn_skein/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein
+  source_code_uri: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein
+  changelog_uri: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib