track_open_instances 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 264fbcefa796af11230c90bc8f1221363d3af1515975e8647a694a486499c874
+  data.tar.gz: 7a5129b04a6ff432a8b7641f80b0b18e98ea52a96b8bb45599ba991650558fea
+SHA512:
+  metadata.gz: '0963b6a2fcd9fb91f42dfadc663425365de598b82e1635d8178216ca05da85d19cf1ba8c0bf67807bf3ff650b73558717703ade5772bb516d357b2c2517e363c'
+  data.tar.gz: 57aa5b10f7fc3b96f062cab47985ac5e060aebff83a408293c91339809f68105414b34bff748a016a53f055b23bbf30f37ae3dde43ce05c24a660d59896382f4

data/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no-install commitlint --edit "$1"

data/.markdownlint.yml

@@ -0,0 +1,26 @@
+---
+default: true
+
+# Unordered list indentation
+MD007: { indent: 2 }
+
+# Line length
+MD013: { line_length: 90, tables: false, code_blocks: false }
+
+# Heading duplication is allowed for non-sibling headings
+MD024: { siblings_only: true }
+
+# Do not allow the specified trailing punctuation in a header
+MD026: { punctuation: ".,;:" }
+
+# Order list items must have a prefix that increases in numerical order
+MD029: { style: "ordered" }
+
+# Lists do not need to be surrounded by blank lines
+MD032: false
+
+# Allow raw HTML in Markdown
+MD033: false
+
+# Allow emphasis to be used instead of a heading
+MD036: false

data/.qlty/qlty.toml

@@ -0,0 +1,104 @@
+# This file was automatically generated by `qlty init`.
+# You can modify it to suit your needs.
+# We recommend you to commit this file to your repository.
+#
+# This configuration is used by both Qlty CLI and Qlty Cloud.
+#
+#     Qlty CLI -- Code quality toolkit for developers
+#     Qlty Cloud -- Fully automated Code Health Platform
+#
+# Try Qlty Cloud: https://qlty.sh
+#
+# For a guide to configuration, visit https://qlty.sh/d/config
+# Or for a full reference, visit https://qlty.sh/d/qlty-toml
+config_version = "0"
+
+exclude_patterns = [
+  "*_min.*",
+  "*-min.*",
+  "*.min.*",
+  "**/*.d.ts",
+  "**/.yarn/**",
+  "**/bower_components/**",
+  "**/build/**",
+  "**/cache/**",
+  "**/config/**",
+  "**/db/**",
+  "**/deps/**",
+  "**/dist/**",
+  "**/extern/**",
+  "**/external/**",
+  "**/generated/**",
+  "**/Godeps/**",
+  "**/gradlew/**",
+  "**/mvnw/**",
+  "**/node_modules/**",
+  "**/protos/**",
+  "**/seed/**",
+  "**/target/**",
+  "**/testdata/**",
+  "**/vendor/**",
+  "**/assets/**",
+]
+
+test_patterns = [
+  "**/test/**",
+  "**/spec/**",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/*_test.*",
+  "**/*_spec.*",
+  "**/test_*.*",
+  "**/spec_*.*",
+]
+
+[smells]
+mode = "comment"
+
+[[source]]
+name = "default"
+default = true
+
+[[plugin]]
+name = "actionlint"
+
+[[plugin]]
+name = "checkov"
+
+[[plugin]]
+name = "golangci-lint"
+mode = "comment"
+
+[[plugin]]
+name = "markdownlint"
+version = "0.41.0"
+mode = "comment"
+
+[[plugin]]
+name = "prettier"
+
+# [[plugin]]
+# name = "radarlint-ruby"
+
+[[plugin]]
+name = "ripgrep"
+mode = "comment"
+
+# [[plugin]]
+# name = "rubocop"
+# version = "1.75.2"
+# package_file = "Gemfile"
+# package_filters = ["rubocop"]
+
+[[plugin]]
+name = "trivy"
+drivers = [
+  "config",
+  "fs-vuln",
+]
+
+[[plugin]]
+name = "trufflehog"
+
+[[plugin]]
+name = "yamllint"

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,18 @@
+---
+inherit_gem:
+  main_branch_shared_rubocop_config: config/rubocop.yml
+
+Metrics/MethodLength:
+  Exclude:
+    - "spec/spec_helper.rb"
+    - "spec/**/*_spec.rb"
+
+Metrics/AbcSize:
+  Exclude:
+    - "spec/spec_helper.rb"
+    - "spec/**/*_spec.rb"
+
+AllCops:
+  # Pin this project to Ruby 3.1 in case the shared config above is
+  # upgraded to 3.2 or later.
+  TargetRubyVersion: 3.1

data/.yamllint.yml

@@ -0,0 +1,12 @@
+---
+extends: default
+
+ignore: |
+  node_modules
+
+rules:
+  braces:
+    min-spaces-inside: 1
+    max-spaces-inside: 1
+  truthy:
+    check-keys: false

data/.yardopts

@@ -0,0 +1,9 @@
+--no-private
+--hide-void-return
+--markup-provider=redcarpet
+--markup markdown
+--readme README.md
+- CHANGELOG.md
+- CONTRIBUTING.md
+- RELEASING.md
+- LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Change Log
+
+## v0.1.0 (2025-04-08)
+
+[Full Changelog](https://github.com/main-branch/track_open_instances/compare/f0fb459..v0.1.0)
+
+Changes:
+
+- f2d5318 chore: remove radarline-ruby from qlty checks
+- 177eba8 chore: fix formatting errors reported by `qlty fmt`
+- 943359f build: remove rubocop plugin from qlty
+- 476f271 chore: integrate yamllint
+- 56811ca fix: add qlty configuration in order to run qlty checks locally
+- e83546a fix: fix continuous integration workflow issues reported by qlty.sh
+- 6f67aed test: add predicate methods to determine the Ruby engine and platform
+- 34e3829 build: generate JSON coverage report for qlty.sh coverage reporting
+- 9db2052 docs: update README links
+- 937a971 build: update code coverage reporting
+- f0fb459 feat: initial implementation of TrackOpenInstances

data/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to track_open_instances
+
+Thank you for your interest in contributing to the track_open_instances project!
+
+This document gives the guidelines for contributing to this project.
+These guidelines may not fit every situation. When contributing use your best
+judgement.
+
+Propose changes to these guidelines with a pull request.
+
+## How to contribute to track_open_instances
+
+You can contribute in two ways:
+
+1. [Report an issue or make a feature request](#how-to-report-an-issue-or-make-a-feature-request)
+2. [Submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
+
+## How to report an issue or make a feature request
+
+track_open_instances utilizes [GitHub Issues](https://help.github.com/en/github/managing-your-work-on-github/about-issues)
+for issue tracking and feature requests.
+
+Report an issue or feature request by [creating a track_open_instances Github issue](https://github.com/main-branch/track_open_instances/issues/new).
+Fill in the template to describe the issue or feature request the best you can.
+
+## How to submit a code or documentation change
+
+There is three step process for code or documentation changes:
+
+1. [Commit your changes to a fork of track_open_instances](#commit-changes-to-a-fork-of-track_open_instances)
+2. [Create a pull request](#create-a-pull-request)
+3. [Get your pull request reviewed](#get-your-pull-request-reviewed)
+
+### Commit changes to a fork of track_open_instances
+
+Make your changes in a fork of the track_open_instances repository.
+
+### Create a pull request
+
+See [this article](https://help.github.com/articles/about-pull-requests/) if you
+are not familiar with GitHub Pull Requests.
+
+Follow the instructions in the pull request template.
+
+### Get your pull request reviewed
+
+Code review takes place in a GitHub pull request using the
+[the Github pull request review feature](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews).
+
+Once your pull request is ready for review, request a review from at least one of the
+[code owners](https://github.com/orgs/main-branch/teams/track_open_instances-codeowners/members).
+
+During the review process, you may need to make additional commits which would
+need to be squashed. It may also be necessary to rebase to main again if other
+changes are merged before your PR.
+
+At least one approval is required from a project maintainer before your pull
+request can be merged. The maintainer is responsible for ensuring that the pull
+request meets [the project's coding standards](#coding-standards).
+
+## Coding standards
+
+All pull requests must meet these requirements:
+
+### 1 PR = 1 Commit
+
+- All commits for a PR must be squashed into one commit
+- To avoid an extra merge commit, the PR must be able to be merged as [a fast forward merge](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
+- The easiest way to ensure a fast forward merge is to rebase your local branch
+  to the track_open_instances main branch
+
+### Unit tests
+
+- All changes must be accompanied by new or modified RSpec unit tests
+- The entire test suite must pass when `bundle exec rake spec` is run from the
+  project's local working tree
+- The unit test suite must maintain 100% code coverage to pass
+
+### Documentation
+
+- New and updated public methods must have [YARD](https://yardoc.org/)
+  documentation added to them
+  - [The YARD Cheatsheet](https://gist.github.com/thelastinuit/5984665e6ab69d3c0a413a03602c45be)
+    is a good reference
+- New and updated public facing features should be documented in the project's
+  [README.md](README.md)
+- All documentation must pass `yardstick` documentation analysis
+- The documentation suite must maintain 100% documentation to pass
+
+### Continuous Integration
+
+- All tests must pass in the project's [Travis CI](https://travis-ci.org/main-branch/track_open_instances)
+  build before the pull request will be merged.
+- You can simulate what happens in the Travis CI build by running `bundle exec rake` in
+  the projects root directory.
+
+### Other Design Guidelines
+
+- Use keyword args with defaults instead of an opts hash
+
+## Licensing
+
+track_open_instances uses [the MIT license](https://choosealicense.com/licenses/mit/) as
+declared in the [LICENSE](LICENSE) file.
+
+Licensing is very important to open source projects. It helps ensure the
+software continues to be available under the terms that the author desired.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 James Couball
+
+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,153 @@
+# track_open_instances gem
+
+[![Gem Version](https://badge.fury.io/rb/track_open_instances.svg)](https://badge.fury.io/rb/track_open_instances)
+[![Build Status](https://github.com/main-branch/track_open_instances/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/main-branch/track_open_instances/actions/workflows/continuous_integration.yml)
+[![Documentation](https://img.shields.io/badge/Documentation-Latest-green)](https://rubydoc.info/gems/track_open_instances/)
+[![Change Log](https://img.shields.io/badge/CHANGELOG-Latest-green)](https://rubydoc.info/gems/track_open_instances/file/CHANGELOG.md)
+[![Maintainability](https://qlty.sh/badges/52f7402e-ab92-4f8f-9f62-d879ca628adb/maintainability.svg)](https://qlty.sh/gh/main-branch/projects/track_open_instances)
+[![Code Coverage](https://qlty.sh/badges/52f7402e-ab92-4f8f-9f62-d879ca628adb/test_coverage.svg)](https://qlty.sh/gh/main-branch/projects/track_open_instances)
+[![Slack](https://img.shields.io/badge/slack-main--branch/track__open__instances-yellow.svg?logo=slack)](https://main-branch.slack.com/archives/C01CHR7TMM2)
+
+`TrackOpenInstances` is a Ruby mixin designed to help manage resources that require
+explicit cleanup. It provides a simple mechanism to track instances of a
+class from creation until they are explicitly closed or disposed of.
+
+By including this module in classes that manage resources like files, network
+connections, or temporary objects, you can easily monitor if any instances are left
+open, potentially causing resource leaks. The module keeps an internal list
+of all active instances and provides methods to check the count of open instances and
+assert that no instances remain unclosed, which is particularly useful in test
+suites. It also stores the call stack at the time of instance creation
+to aid debugging.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```Ruby
+gem 'track_open_instances'
+```
+
+And then execute:
+
+```Ruby
+bundle install
+```
+
+Or install it directly from the command line:
+
+```Ruby
+gem install track_open_instances
+```
+
+## Usage
+
+Include the `TrackOpenInstances` module in any class where you need to track
+instances that require explicit cleanup.
+
+Call `add_open_instance` when an instance is created. This is typically done in
+`initialize`.
+
+Call `remove_open_instance` when it's cleaned up. This is typically done in a `close`
+method.
+
+```Ruby
+require 'track_open_instances'
+
+# Example class managing a resource
+class ManagedResource
+  include TrackOpenInstances
+
+  attr_reader :id
+
+  def initialize(id)
+    @id = id
+    puts "Opening resource: #{id}"
+    # Register instance for tracking
+    self.class.add_open_instance(self) #
+  end
+
+  def close
+    puts "Closing resource: #{id}"
+    # Remove instance from tracking
+    self.class.remove_open_instance(self) #
+  end
+end
+```
+
+With that integration, you will be able to keep track of all open instances.
+
+```Ruby
+# --- Basic Usage ---
+
+res1 = ManagedResource.new('A')
+res2 = ManagedResource.new('B')
+
+puts "Open count: #{ManagedResource.open_instance_count}" #=> 2
+
+res1.close #
+
+puts "Open count: #{ManagedResource.open_instance_count}" #=> 1
+
+# --- Checking for Leaks (e.g., in tests) ---
+
+# Get a report of open instances
+report = ManagedResource.open_instances_report
+puts report if report #=>
+# There is 1 open ManagedResource instance:
+#  - object_id=...
+#    Call stack when created:
+#      ... (caller stack lines) ...
+
+# Assert no instances are open (raises RuntimeError if any are found)
+begin
+  ManagedResource.assert_no_open_instances #
+rescue RuntimeError => e
+  puts "Assertion failed: #{e.message}"
+end
+# Output: Assertion failed: There is 1 open ManagedResource instance:...
+
+res2.close
+
+# This assertion will now pass
+ManagedResource.assert_no_open_instances #
+puts "All resources closed successfully."
+# Output: All resources closed successfully.
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rake` to run tests, static analysis, and build the gem.
+
+For experimentation, you can also run `bin/console` for an interactive (IRB) prompt that
+automatically requires track_open_instances.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/main-branch/track_open_instances>.
+
+### Commit message guidelines
+
+All commit messages must follow the [Conventional Commits
+standard](https://www.conventionalcommits.org/en/v1.0.0/). This helps us maintain a
+clear and structured commit history, automate versioning, and generate changelogs
+effectively.
+
+To ensure compliance, this project includes:
+
+- A git commit-msg hook that validates your commit messages before they are accepted.
+
+  To activate the hook, you must have node installed and run `npm install`.
+
+- A GitHub Actions workflow that will enforce the Conventional Commit standard as
+  part of the continuous integration pipeline.
+
+  Any commit message that does not conform to the Conventional Commits standard will
+  cause the workflow to fail and not allow the PR to be merged.
+
+### Pull request guidelines
+
+All pull requests must be merged using rebase merges. This ensures that commit
+messages from the feature branch are preserved in the release branch, keeping the
+history clean and meaningful.

data/RELEASING.md

@@ -0,0 +1,9 @@
+# How to release a new track_open_instances gem
+
+Run `create-github-release <release-type>` in the root of a clean working tree.
+
+Where `release-type` is `major`, `minor`, or `patch` depending on the nature of the
+changes. Refer to the labels on each PR since the last release to determine which
+semver release type to specify.
+
+Follow the directions that `create-github-release` after it prepares the release PR.

data/Rakefile

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+desc 'Run the same tasks that the CI build will run'
+if RUBY_PLATFORM == 'java'
+  task default: %w[spec rubocop bundle:audit build]
+else
+  task default: %w[spec rubocop yard bundle:audit build]
+end
+
+# Bundler Audit
+
+require 'bundler/audit/task'
+Bundler::Audit::Task.new
+
+# Bundler Gem Build
+
+require 'bundler'
+require 'bundler/gem_tasks'
+
+# RSpec
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+CLEAN << 'coverage'
+CLEAN << '.rspec_status'
+CLEAN << 'rspec-report.xml'
+
+# Rubocop
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+# YARD
+
+unless RUBY_PLATFORM == 'java'
+  # yard:build
+
+  require 'yard'
+
+  YARD::Rake::YardocTask.new('yard:build') do |t|
+    t.files = %w[lib/**/*.rb examples/**/*]
+    t.options = %w[--no-private]
+    t.stats_options = %w[--list-undoc]
+  end
+
+  CLEAN << '.yardoc'
+  CLEAN << 'doc'
+
+  # yard:audit
+
+  desc 'Run yardstick to show missing YARD doc elements'
+  task :'yard:audit' do
+    sh "yardstick 'lib/**/*.rb'"
+  end
+
+  # yard:coverage
+
+  require 'yardstick/rake/verify'
+
+  Yardstick::Rake::Verify.new(:'yard:coverage') do |verify|
+    verify.threshold = 100
+  end
+
+  # yard
+
+  desc 'Run all YARD tasks'
+  task yard: %i[yard:build yard:audit yard:coverage]
+end

data/commitlint.config.js

@@ -0,0 +1,30 @@
+module.exports = {
+  extends: ["@commitlint/config-conventional"],
+  rules: {
+    "body-leading-blank": [1, "always"],
+    "body-max-line-length": [2, "always", 100],
+    "footer-leading-blank": [1, "always"],
+    "header-max-length": [2, "always", 100],
+    "subject-empty": [2, "never"],
+    "subject-full-stop": [2, "never", "."],
+    "type-case": [2, "always", "lower-case"],
+    "type-empty": [2, "never"],
+    "type-enum": [
+      2,
+      "always",
+      [
+        "build",
+        "chore",
+        "ci",
+        "docs",
+        "feat",
+        "fix",
+        "perf",
+        "refactor",
+        "revert",
+        "style",
+        "test",
+      ],
+    ],
+  },
+};

data/lib/track_open_instances/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TrackOpenInstances
+  # The last released version of this gem
+  VERSION = '0.1.0'
+end

data/lib/track_open_instances.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative 'track_open_instances/version'
+
+# Mixin to track instances of a class that require explicit cleanup
+#
+# This module provides a mechanism to track instances of classes that need
+# to be explicitly closed or cleaned up. It maintains a list of all instances
+# created and allows checking for any unclosed instances, which can help in
+# identifying resource leaks.
+#
+# @example Basic Usage
+#   class ManagedFile
+#     include TrackOpenInstances
+#
+#     attr_reader :path
+#
+#     def initialize(path)
+#       @path = path
+#       # Simulate opening the file
+#       puts "Opening file: #{path}"
+#       # Register the instance for tracking
+#       self.class.add_instance(self)
+#     end
+#
+#     # Implement the close logic specific to the resource
+#     def close
+#       # Simulate closing the file
+#       puts "Closing file: #{path}"
+#       # Remove the instance from tracking
+#       self.class.remove_instance(self)
+#     end
+#   end
+#
+#   file1 = ManagedFile.new('/tmp/file1.txt')
+#   file2 = ManagedFile.new('/tmp/file2.txt')
+#
+#   puts ManagedFile.unclosed_instances.count #=> 2
+#   puts ManagedFile.unclosed_instances.inspect #=> [#<ManagedFile:...>, #<ManagedFile:...>]
+#
+#   file1.close
+#
+#   puts ManagedFile.unclosed_instances.count #=> 1
+#   puts ManagedFile.unclosed_instances.inspect #=> [#<ManagedFile:...>]
+#
+#   # In a test suite's teardown, you might use:
+#   # ManagedFile.assert_no_open_instances # This would raise if file2 wasn't closed
+#
+#   file2.close
+#   ManagedFile.assert_no_open_instances # This will now pass
+#
+# @api public
+module TrackOpenInstances
+  # Represents an open instance of a class that includes TrackOpenInstances
+  #
+  # @attr_reader [Object] instance The tracked instance
+  # @attr_reader [Array<String>] creation_stack The call stack at the time of instance creation
+  #
+  #  This is useful for debugging and identifying where the instance was created.
+  #
+  # @api private
+  class OpenInstance
+    attr_reader :instance, :creation_stack
+
+    # Initializes a new OpenInstance
+    #
+    # @param instance [Object] The tracked instance
+    # @param creation_stack [Array<String>] The call stack at the time of instance creation
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def initialize(instance, creation_stack)
+      @instance = instance
+      @creation_stack = creation_stack
+    end
+  end
+
+  # Ruby hook executed when this module is included in a base class
+  #
+  # Sets up the necessary class instance variables and extends the base
+  # class with ClassMethods.
+  #
+  # @param base [Class] The class including this module
+  #
+  # @return [void]
+  #
+  # @api private
+  def self.included(base)
+    base.extend(ClassMethods)
+    # @!attribute [rw] open_instances
+    #   Internal storage for all tracked instances
+    #   @return [Hash{Integer => OpenInstance}] The list of currently tracked instances
+    base.instance_variable_set(:@open_instances, {}.compare_by_identity)
+    # @!visibility private
+    # @!attribute [r] open_instances_mutex
+    #   Mutex to ensure thread-safe access to the open_instances list
+    base.instance_variable_set(:@open_instances_mutex, Thread::Mutex.new)
+  end
+
+  # Contains class-level methods added to classes including TrackOpenInstances
+  module ClassMethods
+    # @!attribute [r] open_instances
+    #
+    # Direct access to the internal list of tracked instances
+    #
+    # Note: This returns all instances ever tracked unless explicitly removed.
+    # Use `unclosed_instances` for checking leaks. Direct use is uncommon.
+    #
+    # @example
+    #   # Assuming MyResource includes TrackOpenInstances
+    #   res1 = MyResource.new
+    #   res2 = MyResource.new
+    #   res1.close
+    #   MyResource.open_instances #=> [#<MyResource... object_id=res2>] (after res1 removed)
+    #
+    # @return [Array<Object>] The raw list of currently tracked instances
+    #
+    # @api private
+    def open_instances
+      @open_instances_mutex.synchronize do
+        @open_instances.dup.freeze
+      end
+    end
+
+    # Adds an instance to the tracking list (thread-safe)
+    #
+    # Typically called automatically by the instance's `initialize` method.
+    #
+    # @param instance [Object] The instance to add
+    #
+    # @return [void]
+    #
+    # @api private
+    def add_open_instance(instance)
+      @open_instances_mutex.synchronize do
+        @open_instances[instance] = OpenInstance.new(instance, caller(3..))
+      end
+    end
+
+    # Removes an instance from the tracking list (thread-safe)
+    #
+    # Typically called automatically by the instance's `close` method.
+    #
+    # @param instance [Object] The instance to remove
+    #
+    # @return [void]
+    #
+    # @api private
+    def remove_open_instance(instance)
+      @open_instances_mutex.synchronize do
+        @open_instances.delete(instance)
+      end
+    end
+
+    # The number of currently open instances
+    #
+    # @example
+    #   res1 = MyResource.new
+    #   res2 = MyResource.new
+    #   MyResource.open_instance_count #=> 1
+    #
+    # @return [Integer]
+    #
+    # @api public
+    #
+    def open_instance_count
+      @open_instances_mutex.synchronize do
+        @open_instances.size
+      end
+    end
+
+    # Generates a report string listing unclosed instances and their creation stacks
+    #
+    # Useful for debugging resource leaks. Returns nil if no instances are unclosed.
+    #
+    # @example
+    #   res = MyResource.new
+    #   puts MyResource.open_instances_report
+    #   There is 1 open MyResource instance(s):
+    #   - object_id=701
+    #     Created at:
+    #       (caller stack line 1)
+    #       (caller stack line 2)\n..."
+    #
+    # @return [String, nil] A formatted report string or nil if none are open
+    #
+    # @api public
+    def open_instances_report
+      @open_instances_mutex.synchronize do
+        return nil if @open_instances.count.zero?
+
+        String.new.tap do |report|
+          report << open_instances_report_header
+          report << open_instances_report_body
+        end
+      end
+    end
+
+    # The header string for the report
+    #
+    # @return [String]
+    #
+    # @api private
+    #
+    def open_instances_report_header
+      count = @open_instances.count
+
+      "There #{count == 1 ? 'is' : 'are'} #{count} " \
+        "open #{self.class} instance#{count == 1 ? '' : 's'}:\n"
+    end
+
+    # The body of the report detailing each open instance
+    #
+    # @return [String]
+    #
+    # @api private
+    #
+    def open_instances_report_body
+      String.new.tap do |body|
+        @open_instances.each do |instance, open_instance|
+          body << " - object_id=#{instance.object_id}\n"
+          body << "   Call stack when created:\n"
+          open_instance.creation_stack.reverse.each { |line| body << "     #{line}\n" }
+        end
+      end
+    end
+
+    # Asserts that no instances of the class remain unclosed
+    #
+    # Raises a ProcessExecuter::Error with a detailed report if any instances
+    # are found to be unclosed. Commonly used in test suite teardown blocks.
+    #
+    # @example
+    #   # In RSpec teardown (e.g., after(:each))
+    #   MyResource.assert_no_open_instances
+    #
+    # @raise [RuntimeError] If any instances are found unclosed
+    #
+    # @return [void]
+    #
+    # @api public
+    def assert_no_open_instances
+      report = open_instances_report
+      raise(report.to_s) if report
+    end
+  end
+end

data/package.json

@@ -0,0 +1,11 @@
+{
+  "devDependencies": {
+    "@commitlint/cli": "^19.5.0",
+    "@commitlint/config-conventional": "^19.5.0",
+    "husky": "^9.1.0"
+  },
+  "scripts": {
+    "postinstall": "husky",
+    "prepare": "husky"
+  }
+}

data/pre-commit

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+
+##
+# Run this before doing a commit.  To ensure this happens, after cloning this
+# repository, run bin/setup from the projects root directory
+
+echo 'Performing pre-commit checks'
+
+# Make sure we are testing with the latest version of gems
+# since this is what will get installed in the CI build
+#
+echo "Running 'bundle update'..."
+if ! bundle update > /dev/null; then
+    echo 'FAIL: bundle update failed'
+    exit 1
+fi
+
+# Run all the tests, code/doc analysis, gem build, etc.
+#
+echo "Running 'bundle exec rake default'..."
+if ! bundle exec rake default > /dev/null 2>&1; then
+    echo 'FAIL: Rake default task failed'
+    exit 1
+fi
+
+echo 'SUCCESS'

metadata

@@ -0,0 +1,243 @@
+--- !ruby/object:Gem::Specification
+name: track_open_instances
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- James Couball
+bindir: exe
+cert_chain: []
+date: 2025-04-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: create_github_release
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: main_branch_shared_rubocop_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.75'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: simplecov-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.28
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.28
+- !ruby/object:Gem::Dependency
+  name: yardstick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  A mixin to track instances of Ruby classes that require explicit cleanup,
+  helping to identify potential resource leaks. It maintains a list of
+  created instances and allows checking for any that remain unclosed.
+email:
+- jcouball@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".husky/commit-msg"
+- ".markdownlint.yml"
+- ".qlty/qlty.toml"
+- ".rspec"
+- ".rubocop.yml"
+- ".yamllint.yml"
+- ".yardopts"
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- RELEASING.md
+- Rakefile
+- commitlint.config.js
+- lib/track_open_instances.rb
+- lib/track_open_instances/version.rb
+- package.json
+- pre-commit
+homepage: https://github.com/main-branch/track_open_instances
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/main-branch/track_open_instances
+  source_code_uri: https://github.com/main-branch/track_open_instances
+  documentation_uri: https://rubydoc.info/gems/track_open_instances/0.1.0
+  changelog_uri: https://rubydoc.info/gems/track_open_instances/0.1.0/file/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- 'Platform: Mac, Linux, or Windows'
+- 'Ruby: MRI 3.1 or later, TruffleRuby 24 or later, or JRuby 9.4 or later'
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A mixin to ensure that all instances of a class are closed
+test_files: []