rubocop-yaml 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e7da8d1f4ee4acbde7506fbfd99365f82f83a3b78fd9dddf4125f30ee3afedd0
+  data.tar.gz: 9bc6713ac5b29837b1b78f0ae296f4f29900b564275c7624d124b8edf7946a2a
+SHA512:
+  metadata.gz: c6ebd15cec006677d80ff88ce2ba97e8ed00deaaaf2b8d367d1d3e428807f77222540c42fa8c3d74dfe2bc1ed8aeb5558d45f65ee2fc8e8da9ce23f22e440b1c
+  data.tar.gz: 131958b6d72cdb5ca6f33e8e47ea6849ce671b9869093a382bad88329adcb2de96261a13983c46f0354ac4925123f4c0e27859664dc1fb3b3d20dde7fa6f4c62

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+<!-- CHANGELOG.md -->
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-09-13
+
+- Establish the RuboCop plugin foundation.
+- Add standardized local development commands and CI.
+- Add a safe YAML parser abstraction with immutable nodes and source locations.
+- Add `YAML/Lint/InvalidSyntax`.
+- Add `YAML/Lint/DuplicateKey`.
+- Add opt-in `YAML/Style/KeyOrdering`.
+- Add opt-in `YAML/Style/KeyGrouping`.
+- Add opt-in local JSON Schema validation.
+- Add deterministic Compose and GitHub Actions schema autodetection.
+- Add Rails database environment consistency checks.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stan Carver II
+
+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,123 @@
+<!-- README.md -->
+# RuboCop YAML
+
+RuboCop YAML brings deterministic YAML syntax, style, schema, and Rails-configuration checks into RuboCop while preserving comments, anchors, aliases, and document structure.
+
+## Status
+
+Version 0.1.0 is the first public release. Its existing semantics are the baseline for real-world dogfooding; new behavior should be driven by confirmed usage rather than speculative fixtures.
+
+## Requirements
+
+- Ruby 3.2 or newer
+- RuboCop 1.72 or newer and earlier than 2.0
+
+The gem is framework-independent. Rails is not a runtime dependency; Rails-specific cops operate on configuration files by path and structure.
+
+## Installation
+
+Add the gem to the development and test groups in your `Gemfile`:
+
+```ruby
+group :development, :test do
+  gem "rubocop-yaml", "~> 0.1", require: false
+end
+```
+
+Run `bundle install`, then register the plugin in `.rubocop.yml`:
+
+```yaml
+plugins:
+  - rubocop-yaml
+```
+
+RuboCop YAML automatically includes `**/*.yml` and `**/*.yaml` files.
+
+## Cops
+
+| Cop | Default | Purpose |
+| --- | ---: | --- |
+| `YAML/Lint/InvalidSyntax` | Enabled | Reports malformed YAML at the parser location |
+| `YAML/Lint/DuplicateKey` | Enabled | Reports silent duplicate scalar keys |
+| `YAML/Style/KeyOrdering` | Disabled | Enforces alphabetical or configured key order |
+| `YAML/Style/KeyGrouping` | Disabled | Enforces semantic groups and optional spacing |
+| `YAML/Schema/Validation` | Disabled | Validates against local or autodetected JSON Schemas |
+| `YAML/Rails/DatabaseEnvironmentConsistency` | Enabled for `config/database.yml` | Reports missing Rails environments and required keys |
+
+## Configuration examples
+
+Configure explicit key order without enabling autocorrection:
+
+```yaml
+YAML/Style/KeyOrdering:
+  Enabled: true
+  EnforcedStyle: configured
+  Keys:
+    - name
+    - image
+    - environment
+    - volumes
+```
+
+Map project files to local JSON Schemas:
+
+```yaml
+YAML/Schema/Validation:
+  Enabled: true
+  Schemas:
+    "config/services/*.yml": "schemas/service.json"
+```
+
+With `AutoDetect: true`, schema validation recognizes Compose files and `.github/workflows/*.yml` using pinned, vendored schemas. Explicit `Schemas` mappings take precedence.
+
+Customize Rails database expectations when an application uses nonstandard environments or inherited keys:
+
+```yaml
+YAML/Rails/DatabaseEnvironmentConsistency:
+  RequiredEnvironments:
+    - development
+    - test
+    - staging
+    - production
+  RequiredKeys:
+    - adapter
+    - database
+  AllowMergeKeys: true
+```
+
+## Known limitations
+
+- No cop autocorrects YAML in 0.1.0. Rewriting YAML safely across comments, aliases, anchors, merge keys, and ordering semantics requires dedicated research.
+- Schema validation never retrieves remote references implicitly. Use local, reviewed schemas.
+- The schema registry currently autodetects only Docker Compose and GitHub Actions workflows.
+- The Rails database cop analyzes YAML statically. ERB-looking content is preserved as scalar text and never executed.
+- Ordering and grouping cops skip mappings with complex or merge keys when enforcing an order could misrepresent YAML semantics.
+- Parsing follows the Psych behavior supplied by the active Ruby version; parser edge cases will be expanded through dogfooding and a dedicated torture suite.
+
+## Development and verification
+
+Run `bin/setup`, then `bin/ci`. Use `bin/rspec` and `bin/rubocop` with passthrough arguments for focused checks.
+
+`bin/package` builds the gem and verifies that runtime configuration, vendored schemas, Ruby code, and RBS signatures are present. `bin/e2e` installs that artifact into an isolated gem home and proves RuboCop plugin discovery against a Rails-shaped fixture outside the repository load path.
+
+See the [documentation index](docs/README.md) for architecture notes and the [release runbook](docs/releasing.md) for trusted-publishing setup and release verification.
+
+## Project layout
+
+- `lib/` contains the plugin, cops, and public API.
+- `config/` contains default RuboCop configuration and pinned schemas.
+- `sig/` contains public RBS contracts.
+- `spec/` contains behavior, integration, and coverage checks.
+- `docs/` contains architecture and release documentation.
+- `bin/` contains repeatable development, package, and external-fixture commands.
+
+## License
+
+RuboCop YAML is available under the [MIT License](LICENSE).
+
+Source: [github.com/scarver2/rubocop-yaml](https://github.com/scarver2/rubocop-yaml)
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/config/default.yml

@@ -0,0 +1,59 @@
+# config/default.yml
+AllCops:
+  Include:
+    - "**/*.yaml"
+    - "**/*.yml"
+
+YAML/Lint/InvalidSyntax:
+  Description: Reports malformed YAML using the parser's best source location.
+  Enabled: true
+  VersionAdded: "0.1"
+
+YAML/Lint/DuplicateKey:
+  Description: Reports repeated scalar keys within the same YAML mapping.
+  Enabled: true
+  VersionAdded: "0.1"
+
+YAML/Style/KeyOrdering:
+  Description: Enforces alphabetical or explicitly configured mapping-key order.
+  Enabled: false
+  EnforcedStyle: alphabetical
+  SupportedStyles:
+    - alphabetical
+    - configured
+  Keys: []
+  VersionAdded: "0.1"
+
+YAML/Style/KeyGrouping:
+  Description: Groups semantically related YAML keys in a configured order.
+  Enabled: false
+  Groups: []
+  Scopes:
+    - "*"
+  UnknownKeys: last
+  RequireBlankLines: false
+  VersionAdded: "0.1"
+
+YAML/Schema/Validation:
+  Description: Validates YAML documents against configured local JSON Schemas.
+  Enabled: false
+  AutoDetect: true
+  Debug: false
+  Schemas: {}
+  VersionAdded: "0.1"
+
+YAML/Rails/DatabaseEnvironmentConsistency:
+  Description: Requires consistent environments and keys in Rails database configuration.
+  Enabled: true
+  Include:
+    - "**/config/database.yml"
+    - "**/config/database.yaml"
+  RequiredEnvironments:
+    - development
+    - test
+    - production
+  RequiredKeys:
+    - adapter
+    - database
+  AllowMergeKeys: true
+  VersionAdded: "0.1"

data/config/schemas/compose.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://rubocop-yaml.dev/schemas/compose-spec-2026-08",
+  "type": "object",
+  "required": ["services"],
+  "properties": {
+    "name": { "type": "string" },
+    "services": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "image": { "type": "string" },
+          "build": { "type": ["string", "object"] },
+          "command": { "type": ["string", "array"] },
+          "environment": { "type": ["object", "array"] },
+          "ports": { "type": "array" },
+          "volumes": { "type": "array" },
+          "depends_on": { "type": ["object", "array"] }
+        }
+      }
+    },
+    "networks": { "type": "object" },
+    "volumes": { "type": "object" },
+    "configs": { "type": "object" },
+    "secrets": { "type": "object" }
+  },
+  "additionalProperties": false
+}

data/config/schemas/github-actions.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://rubocop-yaml.dev/schemas/github-actions-schema-store-2026-08",
+  "type": "object",
+  "required": ["on", "jobs"],
+  "properties": {
+    "name": { "type": "string" },
+    "run-name": { "type": "string" },
+    "on": { "type": ["string", "array", "object"] },
+    "permissions": { "type": ["string", "object"] },
+    "env": { "type": "object" },
+    "defaults": { "type": "object" },
+    "concurrency": { "type": ["string", "object"] },
+    "jobs": { "type": "object", "minProperties": 1 }
+  },
+  "additionalProperties": false
+}

data/docs/README.md

@@ -0,0 +1,21 @@
+<!-- docs/README.md -->
+# Documentation
+
+- The parser layer owns safe YAML parsing and source locations.
+- Cops own policy and native RuboCop offense presentation.
+- Schema checks never retrieve remote resources implicitly.
+- `YAML/Style/KeyOrdering` ignores unknown keys in configured mode and skips mappings containing merge or complex keys. It intentionally has no autocorrection so comments and YAML semantics remain untouched.
+- `YAML/Style/KeyGrouping` accepts named key groups, dot-separated nested scopes, `last` or `ignore` handling for unknown keys, and optional blank-line separation. It does not autocorrect.
+- `YAML/Schema/Validation` maps project-relative file globs to local JSON Schema paths. Schemas are cached per run, local references are supported, and remote references are rejected by the validator's default resolver.
+- Schema autodetection recognizes Compose files and `.github/workflows/*.yml`. Explicit mappings take precedence, `AutoDetect: false` disables the registry, and `Debug: true` prints the selected pinned schema identity.
+- `YAML/Rails/DatabaseEnvironmentConsistency` statically checks `config/database.yml` for required environments and keys, including keys inherited through anchors and merge aliases. Configure `RequiredEnvironments`, `RequiredKeys`, or `AllowMergeKeys` to avoid false positives in nonstandard deployments. ERB is preserved as scalar text and is never executed.
+
+## Further reading
+
+- Development and testing instructions live in the project [README](../README.md).
+- [Releasing](releasing.md) documents package verification, trusted publishing, and rollback boundaries.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/docs/releasing.md

@@ -0,0 +1,35 @@
+<!-- docs/releasing.md -->
+# Releasing RuboCop YAML
+
+RuboCop YAML publishes from GitHub Actions with RubyGems trusted publishing. The release workflow accepts tags matching `v*`, verifies that the tag matches `RuboCop::Yaml::VERSION`, runs the complete project checks, installs the packaged gem into an isolated Rails-shaped fixture, and then invokes the official RubyGems release action.
+
+## One-time trusted publisher setup
+
+Create a pending trusted publisher in the RubyGems account that will own `rubocop-yaml`:
+
+- Gem name: `rubocop-yaml`
+- Repository owner: `scarver2`
+- Repository name: `rubocop-yaml`
+- Workflow filename: `release.yml`
+- GitHub environment: `release`
+
+The repository must also have a GitHub Actions environment named `release`. Configure required reviewers there when an explicit deployment approval is desired. No long-lived RubyGems API key belongs in GitHub secrets.
+
+## Release checklist
+
+1. Confirm the release commit is on `master` and the worktree is clean.
+2. Confirm `CHANGELOG.md` has a dated entry matching the version.
+3. Run `bin/ci` to execute specs, coverage, RuboCop, RBS validation, and package inspection.
+4. Run `bin/e2e` to install the built gem in an isolated gem home and lint a Rails-shaped fixture.
+5. Create and push the signed release tag, such as `v0.1.0`.
+6. Approve the `release` environment deployment if protection rules require it.
+7. Verify the GitHub Actions release job, the RubyGems version, and the generated GitHub release/tag page.
+
+## Failure and rollback boundaries
+
+Do not move or reuse a published version tag. If verification fails before publication, fix the release branch and create the tag only after the corrected commit reaches `master`. RubyGems releases are immutable; if a defective version is published, document the defect, release a new patch version, and yank only when leaving the version available would materially harm users.
+
+—
+Stan Carver II
+Made in Texas 🤠
+https://stancarver.com

data/lib/rubocop/cop/yaml/base.rb

@@ -0,0 +1,27 @@
+# lib/rubocop/cop/yaml/base.rb
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Cop
+    module YAML
+      class Base < RuboCop::Cop::Base
+        private
+
+        def yaml_result
+          @yaml_result ||= RuboCop::Yaml::Parser.new.parse(
+            processed_source.raw_source,
+            path: processed_source.path
+          )
+        end
+
+        def source_range(line, column, length = 1)
+          buffer = processed_source.buffer
+          begin_pos = buffer.line_range(line).begin_pos + column - 1
+          Parser::Source::Range.new(buffer, begin_pos, begin_pos + length)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yaml/lint/duplicate_key.rb

@@ -0,0 +1,54 @@
+# lib/rubocop/cop/yaml/lint/duplicate_key.rb
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module RuboCop
+  module Cop
+    module YAML
+      module Lint
+        class DuplicateKey < Base
+          MSG = "Duplicate key `%<key>s`; first declared on line %<line>d."
+
+          def on_new_investigation # rubocop:disable Metrics/AbcSize
+            return unless yaml_result.success?
+
+            duplicates(yaml_result.stream).each do |key, first|
+              add_offense(
+                source_range(key.location.line, key.location.column, key.value.length),
+                message: format(MSG, key: key.value, line: first.location.line)
+              )
+            end
+          end
+
+          def duplicates(root)
+            find_mappings(root).flat_map { |mapping| mapping_duplicates(mapping) }
+          end
+
+          private
+
+          def find_mappings(node)
+            matches = node.type == :mapping ? [node] : []
+            matches + node.children.flat_map { |child| find_mappings(child) }
+          end
+
+          def mapping_duplicates(mapping)
+            seen = {}
+            mapping.children.each_slice(2).filter_map do |key, _value|
+              next unless scalar_key?(key)
+
+              identity = [key.tag, key.value]
+              first = seen[identity]
+              seen[identity] ||= key
+              [key, first] if first
+            end
+          end
+
+          def scalar_key?(key)
+            key&.type == :scalar && key.value != "<<"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yaml/lint/invalid_syntax.rb

@@ -0,0 +1,26 @@
+# lib/rubocop/cop/yaml/lint/invalid_syntax.rb
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module RuboCop
+  module Cop
+    module YAML
+      module Lint
+        class InvalidSyntax < Base
+          MSG = "Invalid YAML syntax: %<message>s"
+
+          def on_new_investigation
+            diagnostic = yaml_result.diagnostic
+            return unless diagnostic
+
+            add_offense(
+              source_range(diagnostic.line, diagnostic.column),
+              message: format(MSG, message: diagnostic.message)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yaml/rails/database_environment_consistency.rb

@@ -0,0 +1,84 @@
+# lib/rubocop/cop/yaml/rails/database_environment_consistency.rb
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module RuboCop
+  module Cop
+    module YAML
+      module Rails
+        class DatabaseEnvironmentConsistency < Base
+          Finding = Struct.new(:node, :message, keyword_init: true)
+          MISSING_ENV = "Define the `%<environment>s` database environment."
+          MISSING_KEY = "Database environment `%<environment>s` is missing required key `%<key>s`."
+
+          def on_new_investigation
+            return unless database_config? && yaml_result.success?
+
+            configured_findings.each do |finding|
+              node = finding.node
+              add_offense(source_range(node.location.line, node.location.column, node.value&.length || 1), message: finding.message)
+            end
+          end
+
+          def findings(stream, required_environments:, required_keys:, allow_merge_keys: true)
+            root = stream.children.first&.children&.first
+            return [] unless root&.type == :mapping
+
+            entries = root.children.each_slice(2).to_h { |key, value| [key.value, [key, value]] }
+            anchors = anchor_mappings(root)
+            required_environments.flat_map do |environment|
+              environment_findings(root, entries, anchors, environment, required_keys, allow_merge_keys)
+            end
+          end
+
+          private
+
+          def database_config?
+            File.basename(processed_source.path).match?(/\Adatabase\.ya?ml\z/)
+          end
+
+          def configured_findings
+            findings(
+              yaml_result.stream,
+              required_environments: cop_config.fetch("RequiredEnvironments", %w[development test production]),
+              required_keys: cop_config.fetch("RequiredKeys", %w[adapter database]),
+              allow_merge_keys: cop_config.fetch("AllowMergeKeys", true)
+            )
+          end
+
+          def environment_findings(root, entries, anchors, environment, required_keys, allow_merge_keys) # rubocop:disable Metrics/ParameterLists
+            key, mapping = entries[environment]
+            return [Finding.new(node: root, message: format(MISSING_ENV, environment: environment))] unless key
+            return required_keys.map { |required| missing_key(key, environment, required) } unless mapping.type == :mapping
+
+            present = effective_keys(mapping, anchors, allow_merge_keys)
+            required_keys.filter_map { |required| missing_key(key, environment, required) unless present.include?(required) }
+          end
+
+          def missing_key(node, environment, key)
+            Finding.new(node: node, message: format(MISSING_KEY, environment: environment, key: key))
+          end
+
+          def anchor_mappings(node)
+            own = node.type == :mapping && node.anchor ? { node.anchor => node } : {}
+            node.children.each_with_object(own) { |child, anchors| anchors.merge!(anchor_mappings(child)) }
+          end
+
+          def effective_keys(mapping, anchors, allow_merge_keys)
+            keys = Set.new
+            mapping.children.each_slice(2) do |key, value|
+              if key.value == "<<" && allow_merge_keys
+                merged = anchors[value.anchor]
+                keys.merge(effective_keys(merged, anchors, false)) if merged
+              else
+                keys << key.value
+              end
+            end
+            keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yaml/schema/validation.rb

@@ -0,0 +1,51 @@
+# lib/rubocop/cop/yaml/schema/validation.rb
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module RuboCop
+  module Cop
+    module YAML
+      module Schema
+        class Validation < Base
+          MSG = "Schema violation at `%<pointer>s`: %<message>s"
+
+          def on_new_investigation
+            findings.each do |finding|
+              add_offense(
+                source_range(finding.line, finding.column),
+                message: format(MSG, pointer: finding.pointer.empty? ? "/" : finding.pointer, message: finding.message)
+              )
+            end
+            debug_schema
+          rescue RuboCop::Yaml::Schema::Validator::ConfigurationError => e
+            add_offense(source_range(1, 1), message: "Schema configuration error: #{e.message}")
+          end
+
+          private
+
+          def findings
+            validator.validate(
+              source: processed_source.raw_source,
+              path: processed_source.path,
+              schemas: cop_config.fetch("Schemas", {}),
+              root: Dir.pwd,
+              autodetect: cop_config.fetch("AutoDetect", true)
+            )
+          end
+
+          def validator
+            @validator ||= RuboCop::Yaml::Schema::Validator.new
+          end
+
+          def debug_schema
+            return unless cop_config.fetch("Debug", false) && validator.selected_schema
+
+            entry = validator.selected_schema
+            warn("rubocop-yaml: #{processed_source.path} uses #{entry.name} schema #{entry.version} (#{entry.path})")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yaml/style/key_grouping.rb

@@ -0,0 +1,93 @@
+# lib/rubocop/cop/yaml/style/key_grouping.rb
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module RuboCop
+  module Cop
+    module YAML
+      module Style
+        class KeyGrouping < Base
+          Finding = Struct.new(:key, :message, keyword_init: true)
+          ORDER_MSG = "Place `%<key>s` with the earlier `%<group>s` key group."
+          SPACE_MSG = "Separate the `%<group>s` key group with a blank line."
+
+          def on_new_investigation # rubocop:disable Metrics/AbcSize
+            return unless yaml_result.success?
+
+            findings(yaml_result.stream, settings).each do |finding|
+              key = finding.key
+              add_offense(source_range(key.location.line, key.location.column, key.value.length), message: finding.message)
+            end
+          end
+
+          def findings(root, options)
+            groups = options.fetch("Groups")
+            ranks = group_ranks(groups)
+            mappings(root).flat_map do |mapping, path|
+              next [] unless in_scope?(path, options.fetch("Scopes", ["*"]))
+
+              keys = mapping.children.each_slice(2).map(&:first)
+              keys = keys.select { |key| key.type == :scalar && key.value != "<<" }
+              ranked_findings(keys, groups, ranks, options)
+            end
+          end
+
+          private
+
+          def settings
+            cop_config.slice("Groups", "Scopes", "UnknownKeys", "RequireBlankLines")
+          end
+
+          def group_ranks(groups)
+            groups.each_with_index.with_object({}) do |(group, index), ranks|
+              group.fetch("Keys").each { |key| ranks[key] = [index, group.fetch("Name")] }
+            end
+          end
+
+          def mappings(node, path = []) # rubocop:disable Metrics/AbcSize
+            own = node.type == :mapping ? [[node, path]] : []
+            return own + node.children.flat_map { |child| mappings(child, path) } unless node.type == :mapping
+
+            children = node.children.each_slice(2).flat_map do |key, value|
+              key_path = key.type == :scalar ? path + [key.value] : path
+              mappings(value, key_path)
+            end
+            own + children
+          end
+
+          def in_scope?(path, scopes)
+            scopes.include?("*") || scopes.include?(path.join("."))
+          end
+
+          def ranked_findings(keys, groups, ranks, options)
+            unknown_rank = options.fetch("UnknownKeys", "last") == "last" ? groups.length : nil
+            ranked = keys.filter_map do |key|
+              rank, name = ranks.fetch(key.value, [unknown_rank, "unlisted"])
+              [rank, name, key] if rank
+            end
+            order_findings(ranked) + spacing_findings(ranked, options.fetch("RequireBlankLines", false))
+          end
+
+          def order_findings(ranked)
+            ranked.each_cons(2).filter_map do |previous, current|
+              next unless current.first < previous.first
+
+              Finding.new(key: current.last, message: format(ORDER_MSG, key: current.last.value, group: current[1]))
+            end
+          end
+
+          def spacing_findings(ranked, required)
+            return [] unless required
+
+            ranked.each_cons(2).filter_map do |previous, current|
+              next if previous.first == current.first || current.last.location.line > previous.last.location.end_line + 1
+
+              Finding.new(key: current.last, message: format(SPACE_MSG, group: current[1]))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/yaml/style/key_ordering.rb

@@ -0,0 +1,67 @@
+# lib/rubocop/cop/yaml/style/key_ordering.rb
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module RuboCop
+  module Cop
+    module YAML
+      module Style
+        class KeyOrdering < Base
+          MSG = "Place `%<key>s` before `%<previous>s` according to the configured key order."
+
+          def on_new_investigation # rubocop:disable Metrics/AbcSize
+            return unless yaml_result.success?
+
+            violations(yaml_result.stream, style: style, keys: configured_keys).each do |key, previous|
+              add_offense(
+                source_range(key.location.line, key.location.column, key.value.length),
+                message: format(MSG, key: key.value, previous: previous.value)
+              )
+            end
+          end
+
+          def violations(root, style:, keys: [])
+            mappings(root).flat_map do |mapping|
+              scalar_keys = mapping.children.each_slice(2).map(&:first)
+              next [] unless scalar_keys.all? { |key| sortable?(key) }
+
+              ordering_violations(scalar_keys, style, keys)
+            end
+          end
+
+          private
+
+          def mappings(node)
+            own = node.type == :mapping ? [node] : []
+            own + node.children.flat_map { |child| mappings(child) }
+          end
+
+          def ordering_violations(keys, style, configured)
+            ranked = ranked_keys(keys, style, configured)
+            ranked.each_cons(2).filter_map { |previous, key| [key.last, previous.last] if key.first < previous.first }
+          end
+
+          def ranked_keys(keys, style, configured)
+            return keys.map { |key| [key.value.downcase, key] } if style.to_s == "alphabetical"
+
+            indexes = configured.each_with_index.to_h
+            keys.filter_map { |key| [indexes[key.value], key] if indexes.key?(key.value) }
+          end
+
+          def sortable?(key)
+            key&.type == :scalar && key.value != "<<"
+          end
+
+          def style
+            cop_config.fetch("EnforcedStyle", "alphabetical")
+          end
+
+          def configured_keys
+            cop_config.fetch("Keys", [])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/yaml/parser.rb

@@ -0,0 +1,64 @@
+# lib/rubocop/yaml/parser.rb
+# frozen_string_literal: true
+
+require "psych"
+
+module RuboCop
+  module Yaml
+    class Parser
+      Location = Struct.new(:line, :column, :end_line, :end_column, keyword_init: true)
+      Diagnostic = Struct.new(:path, :line, :column, :message, keyword_init: true)
+      Result = Struct.new(:stream, :diagnostic, keyword_init: true) do
+        def success?
+          diagnostic.nil?
+        end
+      end
+
+      class Node
+        attr_reader :type, :value, :children, :location, :anchor, :tag, :plain
+
+        def initialize(type:, value:, children:, location:, anchor:, tag:, plain:) # rubocop:disable Metrics/ParameterLists
+          @type = type
+          @value = value
+          @children = children.freeze
+          @location = location
+          @anchor = anchor
+          @tag = tag
+          @plain = plain
+          freeze
+        end
+      end
+
+      def parse(source, path: "(yaml)")
+        Result.new(stream: convert(Psych.parse_stream(source, filename: path)))
+      rescue Psych::SyntaxError => e
+        Result.new(
+          diagnostic: Diagnostic.new(path: path, line: e.line, column: e.column, message: e.problem)
+        )
+      end
+
+      private
+
+      def convert(node) # rubocop:disable Metrics/AbcSize
+        Node.new(
+          type: node.class.name.split("::").last.downcase.to_sym,
+          value: node.respond_to?(:value) ? node.value : nil,
+          children: Array(node.children).map { |child| convert(child) },
+          location: location(node),
+          anchor: node.respond_to?(:anchor) ? node.anchor : nil,
+          tag: node.respond_to?(:tag) ? node.tag : nil,
+          plain: node.respond_to?(:plain) ? node.plain : nil
+        )
+      end
+
+      def location(node)
+        Location.new(
+          line: node.start_line + 1,
+          column: node.start_column + 1,
+          end_line: node.end_line + 1,
+          end_column: node.end_column + 1
+        )
+      end
+    end
+  end
+end

data/lib/rubocop/yaml/plugin.rb

@@ -0,0 +1,34 @@
+# lib/rubocop/yaml/plugin.rb
+# frozen_string_literal: true
+
+require "lint_roller"
+require "pathname"
+
+require_relative "processed_source"
+
+module RuboCop
+  module Yaml
+    class Plugin < LintRoller::Plugin
+      def about
+        LintRoller::About.new(
+          name: "rubocop-yaml",
+          version: VERSION,
+          homepage: "https://github.com/scarver2/rubocop-yaml",
+          description: "YAML analysis with native RuboCop offenses"
+        )
+      end
+
+      def supported?(context)
+        context.engine == :rubocop
+      end
+
+      def rules(_context)
+        LintRoller::Rules.new(
+          type: :path,
+          config_format: :rubocop,
+          value: Pathname(__dir__).join("../../../config/default.yml")
+        )
+      end
+    end
+  end
+end

data/lib/rubocop/yaml/processed_source.rb

@@ -0,0 +1,25 @@
+# lib/rubocop/yaml/processed_source.rb
+# frozen_string_literal: true
+
+require "rubocop"
+
+module RuboCop
+  module Yaml
+    module ProcessedSource
+      YAML_EXTENSION = /\.ya?ml\z/i
+
+      def from_file(path, ruby_version, parser_engine: :default)
+        return super unless path.to_s.match?(YAML_EXTENSION)
+
+        yaml = File.binread(path)
+        source = new("", ruby_version, path, parser_engine: parser_engine)
+        buffer = ::Parser::Source::Buffer.new(path.to_s, source: yaml)
+        source.instance_variable_set(:@raw_source, yaml)
+        source.instance_variable_set(:@buffer, buffer)
+        source
+      end
+    end
+  end
+end
+
+RuboCop::ProcessedSource.singleton_class.prepend(RuboCop::Yaml::ProcessedSource)

data/lib/rubocop/yaml/schema/registry.rb

@@ -0,0 +1,31 @@
+# lib/rubocop/yaml/schema/registry.rb
+# frozen_string_literal: true
+
+module RuboCop
+  module Yaml
+    module Schema
+      class Registry
+        Entry = Struct.new(:name, :version, :path, keyword_init: true)
+
+        def resolve(path)
+          case path
+          when %r{(?:\A|/)(?:compose|docker-compose)\.ya?ml\z}
+            entry("Docker Compose", "compose-spec-2026-08", "compose.json")
+          when %r{(?:\A|/)\.github/workflows/[^/]+\.ya?ml\z}
+            entry("GitHub Actions", "schema-store-2026-08", "github-actions.json")
+          end
+        end
+
+        private
+
+        def entry(name, version, filename)
+          Entry.new(
+            name: name,
+            version: version,
+            path: File.expand_path("../../../../config/schemas/#{filename}", __dir__)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/yaml/schema/validator.rb

@@ -0,0 +1,131 @@
+# lib/rubocop/yaml/schema/validator.rb
+# frozen_string_literal: true
+
+require "json_schemer"
+require "pathname"
+require "psych"
+
+module RuboCop
+  module Yaml
+    module Schema
+      class Validator
+        Finding = Struct.new(:pointer, :message, :line, :column, keyword_init: true)
+
+        class ConfigurationError < StandardError; end
+
+        attr_reader :selected_schema
+
+        def initialize(parser: Parser.new, registry: Registry.new)
+          @parser = parser
+          @registry = registry
+          @schemas = {}
+        end
+
+        def validate(source:, path:, schemas:, root: Dir.pwd, autodetect: true) # rubocop:disable Metrics/AbcSize
+          schema_path = schema_for(path, schemas, root, autodetect)
+          return [] unless schema_path
+
+          parsed = parser.parse(source, path: path)
+          return [] unless parsed.success?
+
+          data = to_data(parsed.stream.children.first.children.first)
+          schemer(schema_path).validate(data).map { |error| finding(error, parsed.stream) }
+        rescue JSON::ParserError, JSONSchemer::InvalidFileURI, JSONSchemer::UnknownRef, Psych::Exception => e
+          raise ConfigurationError, "#{schema_path}: #{e.message}"
+        end
+
+        private
+
+        attr_reader :parser, :registry, :schemas
+
+        def schema_for(path, mappings, root, autodetect)
+          relative = Pathname(path).absolute? ? Pathname(path).relative_path_from(Pathname(root)).to_s : path
+          match = mappings.find { |glob, _schema| File.fnmatch?(glob, relative, File::FNM_PATHNAME | File::FNM_EXTGLOB) }
+          return select_explicit(File.expand_path(match.last, root)) if match
+          return unless autodetect
+
+          select_registry(registry.resolve(relative))
+        rescue ArgumentError
+          nil
+        end
+
+        def select_explicit(path)
+          @selected_schema = Registry::Entry.new(name: "explicit", version: "project", path: path)
+          path
+        end
+
+        def select_registry(entry)
+          @selected_schema = entry
+          entry&.path
+        end
+
+        def schemer(path)
+          schemas[path] ||= begin
+            pathname = Pathname(path)
+            raise ConfigurationError, "schema does not exist" unless pathname.file?
+            raise ConfigurationError, "schema is malformed" unless JSONSchemer.valid_schema?(pathname)
+
+            JSONSchemer.schema(pathname)
+          end
+        end
+
+        def finding(error, stream)
+          node = node_at(stream, error.fetch("data_pointer"))
+          Finding.new(
+            pointer: error.fetch("data_pointer"),
+            message: error.fetch("error"),
+            line: node.location.line,
+            column: node.location.column
+          )
+        end
+
+        def node_at(stream, pointer)
+          node = stream.children.first.children.first
+          decode_pointer(pointer).each do |part|
+            next_node = child_at(node, part)
+            break unless next_node
+
+            node = next_node
+          end
+          node
+        end
+
+        def child_at(node, part)
+          return node.children[part.to_i] if node.type == :sequence
+          return unless node.type == :mapping
+
+          pair = node.children.each_slice(2).find { |key, _value| key.value == part }
+          pair&.last || pair&.first
+        end
+
+        def decode_pointer(pointer)
+          pointer.split("/").drop(1).map { |part| part.gsub("~1", "/").gsub("~0", "~") }
+        end
+
+        def to_data(node)
+          case node.type
+          when :mapping
+            node.children.each_slice(2).to_h { |key, value| [key.value, to_data(value)] }
+          when :sequence
+            node.children.map { |child| to_data(child) }
+          when :scalar
+            scalar_value(node)
+          else
+            node.value
+          end
+        end
+
+        def scalar_value(node) # rubocop:disable Metrics/AbcSize
+          return node.value unless node.plain
+          return nil if %w[null ~].include?(node.value.downcase)
+          return true if node.value.downcase == "true"
+          return false if node.value.downcase == "false"
+          return node.value.to_i if node.value.match?(/\A[-+]?\d+\z/)
+          return node.value.to_f if node.value.match?(/\A[-+]?(?:\d+\.\d*|\d*\.\d+)(?:e[-+]?\d+)?\z/i)
+
+          node.value
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/yaml/version.rb

@@ -0,0 +1,8 @@
+# lib/rubocop/yaml/version.rb
+# frozen_string_literal: true
+
+module RuboCop
+  module Yaml
+    VERSION = "0.1.0"
+  end
+end

data/lib/rubocop/yaml.rb

@@ -0,0 +1,17 @@
+# lib/rubocop/yaml.rb
+# frozen_string_literal: true
+
+require_relative "yaml/parser"
+require_relative "yaml/processed_source"
+# Plugin registration reads VERSION while the class is defined.
+require_relative "yaml/version"
+require_relative "yaml/plugin"
+require_relative "yaml/schema/registry"
+require_relative "yaml/schema/validator"
+
+require_relative "cop/yaml/lint/duplicate_key"
+require_relative "cop/yaml/lint/invalid_syntax"
+require_relative "cop/yaml/rails/database_environment_consistency"
+require_relative "cop/yaml/schema/validation"
+require_relative "cop/yaml/style/key_grouping"
+require_relative "cop/yaml/style/key_ordering"

data/sig/rubocop/yaml/parser.rbs

@@ -0,0 +1,38 @@
+# sig/rubocop/yaml/parser.rbs
+module RuboCop
+  module Yaml
+    class Parser
+      class Location < Struct[Integer | nil]
+        def line: () -> Integer
+        def column: () -> Integer
+        def end_line: () -> Integer
+        def end_column: () -> Integer
+      end
+
+      class Diagnostic < Struct[Integer | String | nil]
+        def path: () -> String
+        def line: () -> Integer
+        def column: () -> Integer
+        def message: () -> String
+      end
+
+      class Result < Struct[Node | Diagnostic | nil]
+        def stream: () -> Node?
+        def diagnostic: () -> Diagnostic?
+        def success?: () -> bool
+      end
+
+      class Node
+        attr_reader type: Symbol
+        attr_reader value: String?
+        attr_reader children: Array[Node]
+        attr_reader location: Location
+        attr_reader anchor: String?
+        attr_reader tag: String?
+        attr_reader plain: bool?
+      end
+
+      def parse: (String source, ?path: String) -> Result
+    end
+  end
+end

metadata

@@ -0,0 +1,165 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-yaml
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stan Carver II
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+description: A RuboCop plugin for deterministic YAML linting, style, schema, and Rails
+  configuration checks.
+email:
+- howdy@stancarver.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- config/default.yml
+- config/schemas/compose.json
+- config/schemas/github-actions.json
+- docs/README.md
+- docs/releasing.md
+- lib/rubocop/cop/yaml/base.rb
+- lib/rubocop/cop/yaml/lint/duplicate_key.rb
+- lib/rubocop/cop/yaml/lint/invalid_syntax.rb
+- lib/rubocop/cop/yaml/rails/database_environment_consistency.rb
+- lib/rubocop/cop/yaml/schema/validation.rb
+- lib/rubocop/cop/yaml/style/key_grouping.rb
+- lib/rubocop/cop/yaml/style/key_ordering.rb
+- lib/rubocop/yaml.rb
+- lib/rubocop/yaml/parser.rb
+- lib/rubocop/yaml/plugin.rb
+- lib/rubocop/yaml/processed_source.rb
+- lib/rubocop/yaml/schema/registry.rb
+- lib/rubocop/yaml/schema/validator.rb
+- lib/rubocop/yaml/version.rb
+- sig/rubocop/yaml/parser.rbs
+homepage: https://github.com/scarver2/rubocop-yaml
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  default_lint_roller_plugin: RuboCop::Yaml::Plugin
+  source_code_uri: https://github.com/scarver2/rubocop-yaml
+  changelog_uri: https://github.com/scarver2/rubocop-yaml/blob/master/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.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: YAML analysis with native RuboCop offenses
+test_files: []