yarn_skein 0.1.1

checksums.yaml

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

data/.github/actions/ruby-setup/action.yml

@@ -0,0 +1,23 @@
+name: Ruby Setup
+description: Setup Ruby and install dependencies
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/checkout@v5
+
+    - uses: jdx/mise-action@v3
+      with:
+        install: true
+        cache: true
+        mise_toml: |
+          [tools]
+          ruby = "4.0.1"
+
+    - uses: actions/cache@v4
+      with:
+        path: vendor/bundle
+        key: bundle-${{ runner.os }}-${{ hashFiles('Gemfile.lock') }}
+
+    - run: bundle install --jobs 4 --retry 3
+      shell: bash

data/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "04:00"
+  open-pull-requests-limit: 10

data/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+env:
+  BUNDLE_PATH: vendor/bundle
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ./.github/actions/ruby-setup
+      - run: bundle exec standardrb
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: ./.github/actions/ruby-setup
+      - run: bundle exec rspec

data/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Verify gem version matches tag
+        run: |
+          GEM_VERSION=$(ruby -e "puts Gem::Specification.load('yarn_skein.gemspec').version")
+          if [ "$GEM_VERSION" != "${{ steps.version.outputs.VERSION }}" ]; then
+            echo "❌ Version mismatch: gemspec=$GEM_VERSION tag=${{ steps.version.outputs.VERSION }}"
+            exit 1
+          fi
+          echo "✅ Gem version matches tag"
+
+      - name: Verify changelog entry
+        run: |
+          if ! grep -q "## \[${{ steps.version.outputs.VERSION }}\]" CHANGELOG.md; then
+            echo "❌ Version ${{ steps.version.outputs.VERSION }} not found in CHANGELOG.md"
+            exit 1
+          fi
+          echo "✅ Changelog entry verified for ${{ steps.version.outputs.VERSION }}"
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0.1"
+          bundler-cache: true
+
+      - name: Build gem
+        run: gem build yarn_skein.gemspec
+
+      - name: Configure RubyGems credentials
+        run: |
+          mkdir -p ~/.gem
+          echo ":rubygems_api_key: ${{ secrets.RUBYGEMS_API_KEY }}" > ~/.gem/credentials
+          chmod 0600 ~/.gem/credentials
+
+      - name: Publish gem
+        run: gem push *.gem
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          generate_release_notes: true

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [Unreleased]
+
+
+## [0.1.1] - 2026-03-14
+### Added
+- `YarnSkein::Yarn` for modeling a skein's brand, line, yardage, skein weight, and optional fiber content
+- Grist and `yards_per_100g` helpers for comparing yarn density with typed `fiber_units` measurements
+- Weight category lookup via `YarnSkein::WeightCategory` for standard yarn classifications
+- Skein math helpers including `skeins_required`, `total_yardage`, and similar-weight comparisons
+- `YarnSkein::FiberBlend` for representing fiber composition percentages
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"yarn_skein" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["TODO: Write your email address"](mailto:"TODO: Write your email address").

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Meagan Waller
+
+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,200 @@
+# yarn_skein
+
+A Ruby domain model for yarn.
+
+`yarn_skein` models the real structural properties of yarn used in knitting, crochet, and other fiber crafts. It builds on typed measurements (via `fiber_units`) to represent yarn attributes like yardage, skein weight, and grist in a clear and safe way.
+
+Instead of passing around raw numbers like `210` or `100`, yarn properties are expressed using typed units.
+
+```ruby
+210.yards
+100.grams
+```
+
+This makes calculations such as **grist**, **weight category**, and **yardage estimates** straightforward and reliable.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "yarn_skein"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+## Basic Usage
+
+```ruby
+require "yarn_skein"
+
+yarn = YarnSkein::Yarn.new(
+  brand: "Malabrigo",
+  line: "Rios",
+  yardage: 210.yards,
+  skein_weight: 100.grams
+)
+```
+
+## Yarn Properties
+
+A yarn object models the real characteristics of a skein.
+
+```ruby
+yarn.brand
+# => "Malabrigo"
+
+yarn.line
+# => "Rios"
+
+yarn.yardage
+# => 210 yards
+
+yarn.skein_weight
+# => 100 grams
+```
+
+## Grist
+
+**Grist** is the relationship between yardage and weight.
+
+It measures how many yards of yarn exist per gram of fiber.
+
+```ruby
+yarn.grist
+# => 2.1 yards per gram
+```
+
+Internally:
+
+```ruby
+yardage / skein_weight
+```
+
+This metric helps compare yarns with different fiber types or densities.
+
+Example:
+
+| Yarn           | Yardage | Weight | Grist |
+| -------------- | ------- | ------ | ----- |
+| Wool DK        | 210 yd  | 100 g  | 2.1   |
+| Wool Fingering | 400 yd  | 100 g  | 4.0   |
+
+Higher grist = lighter yarn.
+
+## Weight Category
+
+The gem can estimate a yarn’s **standard weight category** from its yardage.
+
+```ruby
+yarn.weight_category
+# => :worsted
+```
+
+Weight categories follow Craft Yarn Council guidelines.
+
+Example:
+
+| Category    | Approx yards per 100g |
+| ----------- | --------------------- |
+| lace        | 800+                  |
+| fingering   | 350–450               |
+| sport       | 300–350               |
+| dk          | 220–300               |
+| worsted     | 180–220               |
+| aran        | 140–180               |
+| bulky       | 100–140               |
+| super_bulky | <100                  |
+
+## Fiber Content
+
+Yarns often contain multiple fibers.
+
+```ruby
+YarnSkein::Yarn.new(
+  brand: "Malabrigo",
+  line: "Rios",
+  fiber_content: [
+    ["merino wool", 100]
+  ],
+  yardage: 210.yards,
+  skein_weight: 100.grams
+)
+```
+
+Future versions may support richer fiber modeling.
+
+## Example: Comparing Yarns
+
+```ruby
+rios = YarnSkein::Yarn.new(
+  brand: "Malabrigo",
+  line: "Rios",
+  yardage: 210.yards,
+  skein_weight: 100.grams
+)
+
+sock = YarnSkein::Yarn.new(
+  brand: "Malabrigo",
+  line: "Sock",
+  yardage: 440.yards,
+  skein_weight: 100.grams
+)
+
+rios.grist
+# => 2.1
+
+sock.grist
+# => 4.4
+```
+
+## Future Capabilities
+
+Planned features include:
+
+* yarn substitution recommendations
+* yardage calculators
+* gauge compatibility helpers
+* skein count estimators
+* stash modeling
+* fiber blend utilities
+
+Example future API:
+
+```ruby
+pattern.required_yardage
+# => 420 yards
+
+yarn.skeins_required(pattern)
+# => 2
+```
+
+## Relationship to fiber_units
+
+`yarn_skein` builds on the `fiber_units` gem.
+
+`fiber_units` provides the measurement system:
+
+```
+4.inches
+210.yards
+100.grams
+```
+
+`yarn_skein` uses those units to model yarn properties.
+
+## Development
+
+Run tests:
+
+```bash
+bundle exec rspec
+```
+
+## License
+
+MIT License

data/Rakefile

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "yard"
+require "yard/rake/yardoc_task"
+require "standard/rake"
+
+# 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
+end
+
+task :default do
+  Rake::Task["standard"].invoke
+  Rake::Task["spec"].invoke
+end

data/lib/yarn_skein/fiber_blend.rb

@@ -0,0 +1,34 @@
+module YarnSkein
+  # Represents the fiber composition of a yarn as percentages by fiber type.
+  class FiberBlend
+    attr_reader :fibers
+
+    # @param fibers [Hash{Symbol => Numeric}] percentages keyed by fiber name
+    # @raise [ArgumentError] if the percentages do not sum to 100
+    def initialize(fibers)
+      total = fibers.values.sum
+
+      unless total == 100
+        raise ArgumentError, "Fiber percentages must sum to 100, but got #{total}"
+      end
+
+      @fibers = fibers
+    end
+
+    # Return the percentage for a given fiber, or zero if it is absent.
+    #
+    # @param fiber [Symbol]
+    # @return [Numeric]
+    def percentage(fiber)
+      fibers[fiber] || 0
+    end
+
+    # Check whether the blend contains a specific fiber.
+    #
+    # @param fiber [Symbol]
+    # @return [Boolean]
+    def contains?(fiber)
+      fibers.key?(fiber)
+    end
+  end
+end

data/lib/yarn_skein/version.rb

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

data/lib/yarn_skein/weight_category.rb

@@ -0,0 +1,30 @@
+module YarnSkein
+  # Maps yardage density to conventional yarn weight categories.
+  module WeightCategory
+    # Yardage-per-100g ranges for each supported weight category.
+    CATEGORY_RANGES = {
+      lace: 800..Float::INFINITY,
+      fingering: 350...800,
+      sport: 300...350,
+      dk: 220...300,
+      worsted: 180...220,
+      aran: 140...180,
+      bulky: 100...140,
+      super_bulky: 0...100
+    }.freeze
+
+    module_function
+
+    # Find the closest standard weight category for a yarn's yardage density.
+    #
+    # @param yards_per_100g [Numeric]
+    # @return [Symbol, nil]
+    def for(yards_per_100g)
+      CATEGORY_RANGES.each do |category, range|
+        return category if range.cover?(yards_per_100g)
+      end
+
+      nil
+    end
+  end
+end

data/lib/yarn_skein/yarn.rb

@@ -0,0 +1,100 @@
+module YarnSkein
+  # Value object describing a yarn line and one skein's physical properties.
+  #
+  # Yardage and weight are stored as `fiber_units` measurements so related
+  # calculations remain unit-safe.
+  class Yarn
+    attr_reader :brand, :line, :yardage, :skein_weight, :fiber_content
+
+    # @param brand [String] yarn manufacturer or brand name
+    # @param line [String] product line name
+    # @param yardage [FiberUnits::Length] yardage contained in one skein
+    # @param skein_weight [FiberUnits::Weight] weight of one skein
+    # @param fiber_content [FiberBlend, nil] optional fiber composition details
+    # @raise [ArgumentError] if yardage or skein weight are not typed fiber_units values
+    def initialize(brand:, line:, yardage:, skein_weight:, fiber_content: nil)
+      raise ArgumentError, "yardage must be a FiberUnits::Length" unless yardage.is_a?(FiberUnits::Length)
+      raise ArgumentError, "skein_weight must be a FiberUnits::Weight" unless skein_weight.is_a?(FiberUnits::Weight)
+
+      @brand = brand
+      @line = line
+      @yardage = yardage
+      @skein_weight = skein_weight
+      @fiber_content = fiber_content
+    end
+
+    # Return the yarn grist as a ratio of yardage to weight.
+    #
+    # @return [FiberUnits::Ratio]
+    def grist
+      yardage / skein_weight
+    end
+
+    # Resolve the yarn's conventional weight category from its yardage density.
+    #
+    # @return [Symbol, nil]
+    def weight_category
+      YarnSkein::WeightCategory.for(yards_per_100g)
+    end
+
+    # Calculate how many yards this yarn yields per 100 grams.
+    #
+    # @return [Float]
+    def yards_per_100g
+      grams = skein_weight.to(:grams).value
+      yards = yardage.to(:yards).value
+
+      (yards / grams) * 100
+    end
+
+    # Compare this yarn's density to another yarn within a 15% tolerance.
+    #
+    # @param other [Yarn]
+    # @return [Boolean]
+    def similar_weight_to?(other)
+      ratio = yards_per_100g / other.yards_per_100g.to_f
+      ratio.between?(0.85, 1.15)
+    end
+
+    # Calculate how many skeins are needed to satisfy a target yardage.
+    #
+    # @param required_yardage [FiberUnits::Length]
+    # @return [Integer]
+    # @raise [ArgumentError] if the argument is not a typed length value
+    def skeins_required(required_yardage)
+      unless required_yardage.is_a?(FiberUnits::Length)
+        raise ArgumentError, "required_yardage must be a FiberUnits::Length"
+      end
+
+      yards_needed = required_yardage.to(:yards).value
+      yards_per_skein = yardage.to(:yards).value
+
+      (yards_needed / yards_per_skein).ceil
+    end
+
+    # Calculate the total yardage provided by a number of skeins.
+    #
+    # @param skein_count [Numeric]
+    # @return [FiberUnits::Length]
+    # @raise [ArgumentError] if the skein count is not positive
+    def total_yardage(skein_count)
+      unless skein_count.is_a?(Numeric) && skein_count > 0
+        raise ArgumentError, "skein_count must be positive"
+      end
+
+      yardage * skein_count
+    end
+
+    # Compare yarn identity by brand, line, yardage, and skein weight.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Yarn) &&
+        brand == other.brand &&
+        line == other.line &&
+        yardage == other.yardage &&
+        skein_weight == other.skein_weight
+    end
+  end
+end

data/lib/yarn_skein.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "fiber_units"
+require_relative "yarn_skein/version"
+require_relative "yarn_skein/weight_category"
+require_relative "yarn_skein/fiber_blend"
+require_relative "yarn_skein/yarn"
+
+# Domain objects for describing yarn skeins, fiber blends, and weight classes.
+#
+# `YarnSkein` builds on `fiber_units` so yardage and weight remain typed
+# values throughout calculations such as grist, total yardage, and category
+# lookups.
+module YarnSkein
+  # Base error class for library-specific failures.
+  class Error < StandardError; end
+end

data/sig/yarn_skein.rbs

@@ -0,0 +1,4 @@
+module YarnSkein
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: yarn_skein
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Meagan Waller
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiber_units
+  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'
+description: FiberUnits provides a comprehensive system for managing and converting
+  measurements in fiber arts projects.
+email:
+- meagan@meaganwaller.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/actions/ruby-setup/action.yml"
+- ".github/dependabot.yml"
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/yarn_skein.rb
+- lib/yarn_skein/fiber_blend.rb
+- lib/yarn_skein/version.rb
+- lib/yarn_skein/weight_category.rb
+- lib/yarn_skein/yarn.rb
+- sig/yarn_skein.rbs
+homepage: https://github.com/meaganewaller/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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Typed measurements for fiber arts.
+test_files: []