fix!: rebuild the unit test suite, document lib/, fix the bugs it found

.gitignore

@@ -7,6 +7,8 @@ Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
+.rspec_status
+vendor/bundle
 doc/
 lib/bundler/man
 pkg

.rspec

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

.yardopts

@@ -0,0 +1,10 @@
+--markup markdown
+--private
+--protected
+--readme README.md
+--output-dir doc
+--title "kitchen-openstack"
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

AGENTS.md

@@ -28,16 +28,23 @@ kitchen-openstack is a Test Kitchen driver for OpenStack. It provisions and dest
 
 ```bash
 bundle install
-bundle exec rake          # runs tests + style + stats (default)
-bundle exec rake test     # unit tests only (RSpec)
-bundle exec rake style    # Cookstyle lint
-bundle exec rake quality  # style + stats
+bundle exec rake            # runs tests + style (default)
+bundle exec rake test       # unit tests only (RSpec)
+bundle exec rake style      # Cookstyle lint
+bundle exec rake quality    # style
+bundle exec rake yard       # render YARD docs to doc/ (not CI-gated)
+bundle exec rake yard_stats # list undocumented methods
 ```
 
 ## Conventions
 
 - Use `Fog::OpenStack::Compute` and `Fog::OpenStack::Network` for cloud interactions
 - Thread safety: use `Mutex` for shared resource pools (e.g., floating IP allocation)
 - Resource finders (`find_image`, `find_flavor`, `find_network`) support regex matching via `/pattern/` syntax
-- Test with RSpec 3 using `let` fixtures, `double` mocks, and `allow_any_instance_of` for Kitchen internals
+- Every method in `lib/` carries YARD tags (`@param`/`@return`/`@raise`). Keep new ones documented; `rake yard_stats` reports gaps but nothing enforces it
+- Specs mirror `lib/` one-to-one: `spec/kitchen/driver/openstack/<module>_spec.rb`
+- Shared spec setup lives in `spec/support/`: the `"with a configured driver"` shared context builds the driver and stubs `instance`; `FogDoubles` builds the Fog stand-ins
+- `verify_partial_doubles` is on. Fog *model* classes take `instance_double`; Fog *service* objects cannot, because Fog defines their methods dynamically at instantiation
+- Unit tests never sleep, hit the network, or read outside a `Dir.mktmpdir`. The one exemption is `openstack_version_spec.rb`, which reads the gemspec and the Release Please manifest to catch version drift, and skips when they are absent. `ENV` is replaced with an `OS_*`-free hash, and the clouds.yaml specs additionally pin `Dir.pwd`, `Dir.home` and `/etc/openstack`, so neither a developer's OpenStack environment nor their real `clouds.yaml`/`secure.yaml` can leak in
+- SimpleCov reports to `coverage/` with no enforced threshold
 - Release automation via Release Please — version bumps go in `lib/kitchen/driver/openstack_version.rb`

CONTRIBUTING.md

@@ -1,8 +1,8 @@
 # Contributing to kitchen-openstack
 
-Thanks for your interest in improving kitchen-openstack. Bug reports, feature requests, and pull requests are all welcome.
+Pull requests are welcome. Please make sure your patches are tested.
 
-This project is actively maintained by the [OSU Open Source Lab](https://osuosl.org/).
+This project is maintained by the [OSU Open Source Lab](https://osuosl.org/).
 
 ## Reporting issues
 
@@ -18,43 +18,70 @@ its config during `finalize_config!`, so diagnose shows the settings actually in
 effect after `clouds.yaml`, the `OS_*` environment variables, and `kitchen.yml`
 have been combined.
 
-## Development setup
+## Getting set up
 
-Clone the repository and install the dependencies:
-
-```sh
-git clone https://github.com/test-kitchen/kitchen-openstack.git
+```bash
+git clone https://github.com/test-kitchen/kitchen-openstack
 cd kitchen-openstack
 bundle install
 ```
 
-## Running the tests
+## Rake tasks
 
-```sh
-bundle exec rake spec      # RSpec unit tests
-bundle exec rake rubocop   # Cookstyle / RuboCop
+```bash
+bundle exec rake            # tests + lint (default)
+bundle exec rake test       # unit tests only
+bundle exec rake style      # Cookstyle lint
+bundle exec rake yard       # render docs to doc/
+bundle exec rake yard_stats # list undocumented methods
 ```
 
+`rake test` runs the `unit` task, and `rake quality` runs `style`.
+
 To run a single spec file:
 
-```sh
+```bash
 bundle exec rspec spec/kitchen/driver/openstack_spec.rb
 ```
 
-Many style offenses can be corrected automatically:
+## How the tests work
 
-```sh
-bundle exec cookstyle -a
-```
+Unit tests live in `spec/`, one file per file in `lib/`, and the whole suite
+runs in well under a second. Nothing in it touches the network or the clock.
+
+Nothing reads the filesystem outside a temp directory either, with one
+deliberate exception: `spec/kitchen/driver/openstack_version_spec.rb` reads the
+gemspec and the Release Please manifest to check that the version number agrees
+in all four places it is written down. Those two examples skip themselves when
+the files are not present.
+
+Your own OpenStack setup cannot change the result. `ENV` is replaced with an
+`OS_*`-free hash, and the `clouds.yaml` specs additionally pin `Dir.pwd`,
+`Dir.home` and `/etc/openstack`, so a real `clouds.yaml` or `secure.yaml` on
+your machine is never read — which also means a real password can never end up
+in an RSpec diff.
+
+Fog *model* objects use `instance_double`. Fog *service* objects cannot, because
+Fog defines their methods dynamically at instantiation — `spec/support/fog_doubles.rb`
+explains this.
+
+Coverage instrumentation is off by default so a single-file run stays fast. Use
+`bundle exec rake coverage` (or set `COVERAGE=1`) to write a report to
+`coverage/`; CI always collects it. It is informational and never fails the run.
+
+## Documentation
+
+`lib/` is documented with YARD. `bundle exec rake yard_stats` lists anything
+undocumented. Neither is enforced in CI, but new methods should come with docs.
 
-The unit tests stub Fog, so they neither build instances nor require an
-OpenStack account.
+When you add or change a configuration option, update the configuration
+reference in `README.md` as well.
 
 ## Manual testing
 
-Changes that touch instance creation, networking, or credential resolution
-should also be exercised against a real cloud, since the stubbed tests cannot
-catch API-level regressions.
+The unit tests never contact a cloud, so changes that touch instance creation,
+networking, or credential resolution should also be exercised against a real
+OpenStack deployment.
 
 Worth exercising separately, since they take different paths:
 
@@ -66,18 +93,16 @@ Worth exercising separately, since they take different paths:
 Confirm after `kitchen destroy` that no instances remain, and that any floating
 IP allocated by the run was released.
 
-## Submitting changes
+## Opening a pull request
 
-1. Fork the repository.
-2. Create a feature branch off `main`.
-3. Make your change, adding or updating tests to cover it.
-4. Run the tests and the linter: `bundle exec rake spec` and
-   `bundle exec rake rubocop`.
-5. Push the branch to your fork and open a pull request.
+1. Fork the repo
+2. Create a topic branch (`git checkout -b my-new-feature`)
+3. Make your change, with tests
+4. Run `bundle exec rake`
+5. Push and open a pull request
 
 Please keep pull requests focused on a single change — it makes review much
-faster. Update the documentation in `README.md` when you add or change a
-configuration option.
+faster.
 
 ## Release process
 

Gemfile

@@ -8,6 +8,11 @@ group :test do
   gem "rake"
   gem "kitchen-inspec"
   gem "rspec", "~> 3.2"
+  gem "simplecov", "~> 0.22"
+end
+
+group :docs do
+  gem "yard"
 end
 
 group :debug do