ivar 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f9a15e9e7bb48429652a717400a82480167376802939f68873b575b3fca766f
+  data.tar.gz: f57d59b780e126287966c116fd83be4848bbbb05268591a3938262fb25395a08
+SHA512:
+  metadata.gz: acc557b2df216279c16bfa299a13017eae33f52622a8f5ef75729b253f00a414f37b8a2e44ae935f3d761a1a02477b3978297751f1e94d39b90a2005fbe6d5fd
+  data.tar.gz: 8acf31444752ee0ef75ac3a4d197448b37cac3f193e8844c57545d6d222e9899586129df849ea3a5e29628608d07a0390591455c82bdbfea60e5bf8826c347dc

data/.augment-guidelines

@@ -0,0 +1,10 @@
+- tests are in minitest
+- use modern Ruby 3.4 style and features, including pattern-matching, endless methods, etc., where appropriate.
+- avoid over-engineering. Prefer basic Ruby data types to building new abstractions. (But extract abstractions when I tell you to.)
+- avoid inline comments. Prefer "explaining variables", intention-revealing method names, and the "composed method" pattern where appropriate. Class, module, and method-documenting comments are fine.
+- De-lint (with standardrb) before committing. Use auto-fix and manually fix the rest.
+- Run all tests and fix failures before committing. 
+- Never "cheat" by making implementation code test-aware. But it is fine to make interactions with the world dependency-injectable for testing purposes.
+- Include a quote of my instruction that led to the commit in the commit message
+- Sign your commit messages with "-- Auggie".
+- Commit and push after making successful changes. 

data/.devcontainer/Dockerfile

@@ -0,0 +1,21 @@
+FROM ruby:3
+
+ARG USERNAME=devcontainer
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+
+# Install basic development tools
+RUN apt update && apt install -y less man-db sudo
+
+# Set up unprivileged local user
+RUN groupadd --gid $USER_GID $USERNAME \
+    && groupadd bundler \
+    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME --shell /bin/bash --groups bundler \
+    && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
+    && chmod 0440 /etc/sudoers.d/$USERNAME
+
+# Set unprivileged user as default user
+USER $USERNAME
+
+# Set `DEVCONTAINER` environment variable to help with orientation
+ENV DEVCONTAINER=true

data/.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+// See https://containers.dev/implementors/json_reference/ for configuration reference
+{
+	"name": "ivar",
+	"build": {
+		"dockerfile": "Dockerfile"
+	},
+	"remoteUser": "devcontainer",
+	"features": {
+		"ghcr.io/devcontainers/features/github-cli:1": {},
+		"ghcr.io/jungaretti/features/ripgrep:1": {}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"connorshea.vscode-ruby-test-adapter",
+				"stripe.endsmart",
+				"testdouble.vscode-standard-ruby",
+				"castwide.solargraph",
+			]
+		}
+	}
+}

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 3.4

data/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "connorshea.vscode-ruby-test-adapter",
+    "stripe.endsmart",
+    "testdouble.vscode-standard-ruby",
+    "castwide.solargraph"
+  ]
+}

data/.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+  "rubyTestExplorer.testFramework": "minitest",
+  "[ruby]": {
+    "editor.formatOnType": true,
+  },
+  "editor.formatOnSave": true,
+  "standardRuby.mode": "enableUnconditionally",
+  "solargraph.diagnostics": true,
+  "solargraph.formatting": true,
+  "solargraph.useBundler": true,
+  "standardRuby.commandPath": "/usr/local/bundle/bin/standardrb",
+  "rubyLsp.formatter": "standard",
+  "standardRuby.autofix": true,
+}

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+## [Unreleased]
+
+## [0.2.0] - 2025-05-01
+
+- Added CheckDynamic module that overrides instance_variable_get/set to check against a list of allowed variables saved at the end of initialization
+
+## [0.1.0] - 2025-04-29
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at avdi@avdi.codes. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Avdi Grimm
+
+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,343 @@
+# Ivar
+
+Ruby instance variables are so convenient - you don't even need to declare them! But... they are also dangerous, because a mispelled variable name results in `nil` instead of an error.
+
+Why not have the best of both worlds? Ivar lets you use plain-old instance variables, and automatically checks for typos.
+
+Ivar waits until an instance is created to do the checking, then uses Prism to look for variables that don't match what was set in initialization. So it's a little bit dynamic, a little bit static. It doesn't encumber your instance variable reads and writes with any extra checking. And with the `:warn_once` policy, it won't overwhelm you with output.
+
+
+## Usage
+
+### Manual Validation
+
+```ruby
+# sandwich.rb
+require "ivar"
+
+class Sandwich
+  include Ivar::Validation
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+    @condiments = ["mayo", "mustard"]
+    check_ivars(add: [:@side])
+  end
+
+  def to_s
+    "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}" \
+    (@side ? "and a side of #{@side}" : "")
+  end
+end
+
+Sandwich.new
+```
+
+```shell
+$ ruby sandwich.rb -w
+sandwich.rb:22: warning: unknown instance variable @chese. Did you mean: @cheese?
+```
+
+### Automatic Validation (Every Instance)
+
+```ruby
+# sandwich_automatic.rb
+require "ivar"
+
+class Sandwich
+  include Ivar::Checked
+
+  def initialize
+    @bread = "white"
+    @cheese = "havarti"
+    @condiments = ["mayo", "mustard"]
+    # no need for explicit check_ivars call
+  end
+
+  def to_s
+    "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}"
+  end
+end
+
+Sandwich.new
+```
+
+```shell
+$ ruby sandwich_automatic.rb -w
+sandwich_automatic.rb:15: warning: unknown instance variable @chese. Did you mean: @cheese?
+```
+
+The `Checked` module automatically calls `check_ivars` after initialization, which means it will emit warnings for every instance of the class.
+
+### Automatic Validation (Once Per Class)
+
+Too many warnings? Try this:
+
+```ruby
+# sandwich_once.rb
+require "ivar"
+
+class Sandwich
+  include Ivar::Checked
+  ivar_check_policy :warn_once
+
+  def initialize
+    @bread = "white"
+    @cheese = "havarti"
+    @condiments = ["mayo", "mustard"]
+    # no need for explicit check_ivars call
+  end
+
+  def to_s
+    "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}"
+  end
+end
+
+Sandwich.new
+```
+
+```shell
+$ ruby sandwich_once.rb -w
+sandwich_once.rb:15: warning: unknown instance variable @chese. Did you mean: @cheese?
+```
+
+Setting `ivar_check_policy :warn_once` makes `check_ivars` use the `warn_once` policy, which means it will emit warnings only for the first instance of each class.
+
+### Pre-declaring Instance Variables
+
+Normally we "declare" variables by setting them in `initialize`. But if you don't have any reason to set them in the initializer, you can still declare them so they won't be flagged.
+
+```ruby
+# sandwich_with_ivar_macro.rb
+require "ivar"
+
+class SandwichWithIvarMacro
+  include Ivar::Checked
+
+  # Pre-declare only instance variables that might be referenced before being set
+  # You don't need to include variables that are always set in initialize
+  ivar :@side
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+    @condiments = ["mayo", "mustard"]
+    # Note: @side is not set here, but it's pre-initialized to nil
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese} and #{@condiments.join(", ")}"
+    # This won't trigger a warning because @side is pre-initialized
+    result += " and a side of #{@side}" if @side
+    result
+  end
+
+  def add_side(side)
+    @side = side
+  end
+end
+
+sandwich = SandwichWithIvarMacro.new
+puts sandwich.to_s  # No warning about @side
+
+sandwich.add_side("chips")
+puts sandwich.to_s
+```
+
+Note: this WILL set the variable to `nil` before `initialize` runs, so if you have code that depends on `defined?(@var)` it may break. If folks want it we might look into non-setting predeclaration.
+
+### Setting ivars from initializer keyword arguments
+
+While we're messing around with ivars, let's fix Ruby's oldest missing convenience feature:
+
+```ruby
+# sandwich_with_kwarg.rb
+require "ivar"
+
+class SandwichWithKwarg
+  include Ivar::Checked
+
+  ivar kwarg: [:@bread, :@cheese, :@condiments, :@pickles, :@side]
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese}"
+    result += " and #{@condiments.join(", ")}" unless @condiments.empty?
+    result += " with pickles" if @pickles
+    result += " and a side of #{@side}" if @side
+    result
+  end
+end
+
+# Create a sandwich with keyword arguments
+sandwich = SandwichWithKwarg.new(
+  bread: "wheat",
+  cheese: "muenster",
+  condiments: ["mayo", "mustard"],
+  side: "chips"
+)
+
+puts sandwich.to_s  # Outputs: A wheat sandwich with muenster and mayo, mustard and a side of chips
+```
+
+Ta-da, no more tedious setting of instance variables from arguments of the same name.
+
+TODO: Find a positional args version of this that makes sense.
+
+### Inheritance
+
+This stuff works with inheritance:
+
+```ruby
+class BaseSandwich
+  include Ivar::Checked
+
+  # Pre-declare only variables that might be referenced before being set
+  # Variables set in initialize (@bread, @cheese) don't need to be pre-declared
+  ivar :@optional_topping
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+  end
+end
+
+class SpecialtySandwich < BaseSandwich
+  # Add more pre-declared instance variables as needed
+  # @condiments is set in initialize, so it doesn't need to be pre-declared
+  ivar :@special_sauce
+
+  def initialize
+    super
+    @condiments = ["mayo", "mustard"]
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@cheese} and #{@condimants.join(", ")}"
+    # @special_sauce is pre-declared, so this won't trigger a warning
+    result += " with #{@special_sauce}" if @special_sauce
+    # @optional_topping is inherited from the parent class
+    result += " and #{@optional_topping}" if @optional_topping
+    result
+  end
+end
+
+SpecialtySandwich.new
+```
+
+```shell
+$ ruby inheritance_example.rb -w
+inheritance_example.rb:17: warning: unknown instance variable @condimants. Did you mean: @condiments?
+```
+
+## Checking Policies
+
+Ivar supports different policies for handling unknown instance variables. You can specify a policy at the global level, class level, or per-check level.
+
+### Available Policies
+
+- `:warn` - Emit warnings for all unknown instance variables (default)
+- `:warn_once` - Emit warnings only once per class
+- `:raise` - Raise an exception for unknown instance variables
+- `:log` - Log unknown instance variables to a logger
+
+### Setting a Global Policy
+
+```ruby
+# Set the global policy to raise exceptions
+Ivar.check_policy = :raise
+
+class Sandwich
+  include Ivar::Validation
+
+  def initialize
+    @bread = "wheat"
+    check_ivars
+  end
+
+  def to_s
+    "A #{@bread} sandwich with #{@chese}"  # This will raise an exception
+  end
+end
+
+Sandwich.new  # Raises: NameError: test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+```
+
+### Setting a Class-Level Policy
+
+```ruby
+class Sandwich
+  include Ivar::Validation
+  extend Ivar::CheckPolicy
+
+  # Set the class-level policy to log
+  ivar_check_policy :log, logger: Logger.new($stderr)
+
+  def initialize
+    @bread = "wheat"
+    check_ivars
+  end
+
+  def to_s
+    "A #{@bread} sandwich with #{@chese}"  # This will log a warning
+  end
+end
+
+Sandwich.new  # Logs: W, [2023-06-01T12:34:56.789123 #12345] WARN -- : test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+```
+
+### Setting a Per-Check Policy
+
+```ruby
+class Sandwich
+  include Ivar::Validation
+
+  def initialize
+    @bread = "wheat"
+    # Use the raise policy for this check
+    check_ivars(policy: :raise)
+  end
+
+  def to_s
+    "A #{@bread} sandwich with #{@chese}"
+  end
+end
+
+Sandwich.new  # Raises: NameError: test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+```
+
+### Using the Checked Module with Policies
+
+The `Checked` module sets a default policy:
+
+- `Checked` sets the policy to `:warn`
+
+You can override the default policy:
+
+```ruby
+class Sandwich
+  include Ivar::Checked
+
+  # Override the default policy
+  ivar_check_policy :raise
+
+  def initialize
+    @bread = "wheat"
+  end
+
+  def to_s
+    "A #{@bread} sandwich with #{@chese}"  # This will raise an exception
+  end
+end
+
+Sandwich.new  # Raises: NameError: test_file.rb:2: unknown instance variable @chese. Did you mean: @cheese?
+```
+
+# Acknowledgements
+
+Thank you to Joel Drapper, for inspiring me with his 
+
+# TODO
+
+- Pre-declare "ghost" variables without setting them
+- Add a module for dynamic checking of instance_variable_get/set

data/Rakefile

@@ -0,0 +1,14 @@
+# 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
+
+require "standard/rake"
+
+task default: %i[test standard]

data/examples/sandwich_inheritance.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class BaseSandwich
+  include Ivar::Checked
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+  end
+
+  def base_to_s
+    "A #{@bread} sandwich with #{@cheese}"
+  end
+end
+
+class SpecialtySandwich < BaseSandwich
+  def initialize
+    super
+    @condiments = ["mayo", "mustard"]
+    @special_sauce = "secret sauce"
+  end
+
+  def to_s
+    result = "#{base_to_s} with #{@condiments.join(", ")}"
+    result += " and #{@special_sause}" # Typo here
+    result
+  end
+end
+
+# Create a specialty sandwich - this will automatically check instance variables
+SpecialtySandwich.new

data/examples/sandwich_with_checked.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithChecked
+  include Ivar::Checked
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+    @condiments = ["mayo", "mustard"]
+    # No need for explicit check_ivars call
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}"
+    result += " and a side of #{@side}" if @side
+    result
+  end
+end
+
+# Create a sandwich - this will automatically check instance variables
+SandwichWithChecked.new

data/examples/sandwich_with_checked_once.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "ivar"
+
+class SandwichWithCheckedOnce
+  include Ivar::Checked
+  ivar_check_policy :warn_once
+
+  def initialize
+    @bread = "wheat"
+    @cheese = "muenster"
+    @condiments = %w[mayo mustard]
+    # No need for explicit check_ivars call
+  end
+
+  def to_s
+    result = "A #{@bread} sandwich with #{@chese} and #{@condiments.join(", ")}"
+    result += " and a side of #{@side}" if @side
+    result
+  end
+end
+
+# Create a sandwich - this will automatically check instance variables once
+puts "Creating first sandwich..."
+SandwichWithCheckedOnce.new
+
+# Create another sandwich - this should not emit warnings
+puts "Creating second sandwich..."
+SandwichWithCheckedOnce.new