doc_guard 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e1710f91fe17ebf7bc8d1f123fc093d6c7e0ad4fc2c42fec0866445f707849e
+  data.tar.gz: 9553cff66d4bc4c958f7a2849c9d317e36e611b662b5816fb8b8a7d476b722b6
+SHA512:
+  metadata.gz: 0a595ad237f74d9757914eabc28766a8b649a84e25d42e7dc7a909dcc99726f718bedd102e3a3463e8820d1ffcaf75a8cda941154f9a3bc5f2285d489acab3ae
+  data.tar.gz: d38e09d03d05e5deb09ce66b9d2148cb2e5ae1989748a565a4489f523ada659d25986a234e300b9acaf9aece4a8d691facf31fd59ee9e9d056deb4d0df2c551e

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.0.0] - 2025-07-02
+
+### Added
+- Initial release of DocGuard gem, a tool to help keep documentation up-to-date with your source code.
+- Support for annotating markdown documentation files with tracked source files via special HTML comments.
+- Available CLI commands (built on Thor):
+  - `doc_guard record` - records current digests of tracked files.
+  - `doc_guard assess` - checks if documentation is up to date based on tracked file changes.
+  - `doc_guard help` - displays available commands and usage instructions.
+- Configuration support:
+  - Load settings via CLI options, environment variables, and YAML config file (`.doc_guard.yml`).
+  - Defaults provided for documentation path and digests store file.
+- Integration-ready for CI/CD pipelines to automate documentation relevance checks.
+- Autoloading using Zeitwerk for cleaner project structure.
+- Comprehensive error handling in CLI with proper exit codes.
+- Basic RSpec tests covering configuration and core functionality.
+
+### Changed
+
+- N/A (initial release)
+
+### Fixed
+
+- N/A (initial release)
+
+---
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Patryk Gramatowski
+
+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,166 @@
+<img src="doc_guard-logo.png" alt="doc_guard logo" width="250" style="display: block; margin: 0 auto"/>
+
+---
+
+### 🛡️ Keep your documentation up-to-date with your code
+
+**DocGuard** is a lightweight, extensible Ruby gem that helps **ensure your documentation remains accurate** as your code evolves. It **tracks** source files referenced in documentation and **warns** when changes occur.
+
+---
+
+### 🚀 Features
+
+- **Automatic File Tracking:**  
+  Easily annotate your documentation files with the source code files they reference. DocGuard automatically detects which files your docs depend on, eliminating manual tracking.
+
+- **Digest Calculation & Change Detection:**  
+  DocGuard computes SHA256 digests (hashes) of tracked files and compares them with previously stored digests to detect any changes. This helps identify when code changes may impact your documentation.
+
+- **Real-time Relevance Assessment:**  
+  Quickly determine if your documentation is still relevant based on the current state of your code. Get instant feedback when your docs might be outdated.
+
+- **Clear and Actionable Reporting:**  
+  Receive concise CLI reports highlighting which files caused potential documentation mismatches, helping you prioritize documentation updates.
+
+- **Fail-safe Exit Codes:**  
+  Integrate DocGuard seamlessly into CI/CD pipelines, it exits with meaningful statuses:
+  - `0` when docs are up to date,
+  - `1` when documentation may be outdated,
+  - `2` on unexpected errors.
+
+- **Flexible CLI (built on [Thor](https://github.com/rails/thor)):**  
+  Easy-to-use commands to assess relevance and extend with future commands for recording or other workflows.
+
+- **Lightweight & Framework Agnostic:**  
+  Works well in Rails projects but designed to be framework-independent and lightweight enough to fit any Ruby codebase.
+
+- **JSON-based Digest Storage:**  
+  Stores digests in a human-readable JSON file, making it easy to audit or manage outside the tool if needed.
+
+
+### 💿 Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add doc_guard
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install doc_guard
+```
+
+or add this line to your application's Gemfile:
+
+```ruby
+gem "doc_guard"
+```
+
+### ⚙️ Usage
+
+#### 1. Annotate Documentation with Tracked Files 📝
+
+To enable DocGuard to track which source files your documentation depends on, add a special HTML comment in your markdown files (e.g., `README.md` or any `.md` files inside a `docs/` folder).
+
+##### How to annotate:
+Insert the following comment at the top (or anywhere relevant) in your markdown file:
+
+```md
+<!-- doc_guard files: [app/models/user.rb, app/services/authenticator.rb] -->
+Your amazing and very important documentation related to the user model and authentication service is here.
+```
+
+#### 2. Record the current state of the relationship between your documentation and your code 💾
+
+```bash
+$ doc_guard record
+```
+
+This stores the current digests of referenced files in `.doc_guard_digests.json.`
+
+#### 3. Assess documentation relevance 🚦
+
+```bash
+$ doc_guard assess
+```
+
+Example output:
+```bash
+‼️ Documentation may be outdated!
+
+📄 docs/user.md
+- app/models/user.rb
+- app/services/authenticator.rb
+
+📄 docs/admin.md
+- app/models/admin.rb
+```
+
+### 🔧 Configuration
+
+DocGuard can be configured in multiple flexible ways to suit different environments (e.g., local development, CI/CD pipelines, GitHub Actions).
+
+Configuration values are resolved using the following priority:
+1. CLI flags
+2. Environment variables
+3. YAML config file (`.doc_guard.yml`)
+4. Internal defaults
+
+#### 🗂️ Available Configuration Options
+
+| Setting                      | CLI Flag                          | ENV Variable                         | YAML Config Key                        | Default Value                 |
+|-----------------------------|------------------------------------|--------------------------------------|----------------------------------------|-------------------------------|
+| Documentation path          | `--documentation-path`            | `DOC_GUARD_DOCUMENTATION_PATH`       | `documentation_path`                  | `"docs"`                      |
+| Digests store file path     | `--digests-store-file-path`       | `DOC_GUARD_DIGESTS_STORE_FILE_PATH`  | `digests_store_file_path`             | `".doc_guard_digests.json"`   |
+| Config file path (for YAML) | `--config-file-path`              | `DOC_GUARD_CONFIG_FILE_PATH`         | *(Not loaded from YAML)*              | `".doc_guard.yml"`            |
+
+*Note: The `config_file_path` is used only to load other settings from a YAML file. It cannot itself be configured via YAML.*
+
+#### 📁 Config File Example
+```yaml
+# .doc_guard.yml
+
+documentation_path: custom_docs
+digests_store_file_path: tmp/doc_guard_state.json
+```
+*Note: Place this file in your project root.*
+
+This configuration approach supports usage in CI/CD pipelines, local development, or scripts, **without any dependency** on Rails or other frameworks.
+
+### 🛣️ Roadmap
+
+The following features are being considered or are actively planned for future releases:
+
+- **External documentation integrations**  
+  Support for syncing and validating documentation that lives outside the main codebase, e.g., Confluence, GitHub Wikis, or other remote documentation tools.
+
+- **Custom digest strategies**  
+  Allow users to define custom strategies for calculating file "change relevance", e.g., ignore comments or whitespace, or weigh different parts of the code differently.
+
+- **AI-assisted relevance analysis**  
+  In the future, integrate with AI systems to help assess whether documentation should be updated based on the semantic nature of recent code changes (e.g., if a developer introduces a new feature but forgets to update corresponding docs).
+
+- **Advanced code–documentation annotation system**  
+  Improve how source code is linked to documentation, potentially with fine-grained annotations (e.g., per method, class, or even logic block), offering a more accurate mapping between code changes and relevant documentation sections.
+
+Have an idea or need a feature? Feel free to [open an issue](https://github.com/patrickgramatowski/doc_guard/issues) or contribute!
+
+### 🧑‍💻 Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/patrickgramatowski/doc_guard. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/patrickgramatowski/doc_guard/blob/master/CODE_OF_CONDUCT.md).
+
+### 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+### 📜 Code of Conduct
+
+Everyone interacting in the DocGuard project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/patrickgramatowski/doc_guard/blob/master/CODE_OF_CONDUCT.md).

data/bin/doc_guard

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "doc_guard"
+
+DocGuard::Cli.start(ARGV)

data/doc_guard.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "lib/doc_guard/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "doc_guard"
+  spec.version = DocGuard::VERSION
+  spec.authors = ["Patryk Gramatowski"]
+  spec.email = ["patrick.gramatowski@gmail.com"]
+
+  spec.summary = "DocGuard helps maintain up-to-date project documentation by tracking files referenced in your docs."
+  spec.description = <<~DESCRIPTION
+    DocGuard helps maintain up-to-date project documentation by tracking files referenced in your docs,
+    calculating file digests, and assessing whether code changes impact your documentation relevance.
+    It provides CLI commands to assess documentation relevance and record the current documentation state,
+    enabling automated enforcement and better documentation quality in Rails and Ruby projects.
+  DESCRIPTION
+
+  spec.homepage = "https://github.com/patrickgramatowski/doc_guard"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/CHANGELOG.md"
+
+  spec.bindir = "bin"
+  spec.executables = [spec.name]
+  spec.require_paths = ["lib"]
+  spec.files = [
+    Dir.glob("{#{spec.require_paths.join(",")}}/**/*.rb"),
+    %W[#{spec.name}.gemspec],
+    %w[CHANGELOG.md README.md LICENSE.txt]
+  ].flatten
+
+  spec.add_dependency "digest", "~> 3.0"
+  spec.add_dependency "thor", "~> 1.3"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+
+  spec.post_install_message = "=> ✅ Setup complete! You can now use `#{spec.name}` on the command line."
+end

data/lib/doc_guard/assess_documentation_relevance/process.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module AssessDocumentationRelevance
+    # Main orchestration class that assesses whether documentation is still relevant
+    # based on digests of referenced files.
+    class Process
+      # Entry point to run the relevance assessment process.
+      #
+      # @param config [DocGuard::Config] Optional configuration.
+      # @return [void]
+      def self.run(config: ::DocGuard::Config.new)
+        new(config: config).call
+      end
+
+      # Initializes the process with the given configuration.
+      #
+      # @param config [DocGuard::Config]
+      def initialize(config: ::DocGuard::Config.new)
+        @config = config
+      end
+
+      # Executes the full relevance assessment pipeline.
+      #
+      # @return [void]
+      def call
+        tracked_files = load_tracked_files
+        stored_digests = load_stored_digests
+        current_digests = calculate_current_digests(tracked_files)
+        mismatches = compare_digests(stored_digests, current_digests)
+        assessment = assess_relevance(tracked_files, mismatches)
+
+        report_assessment(assessment)
+      end
+
+      private
+
+      attr_reader :config
+
+      # Loads files tracked from documentation annotations.
+      #
+      # @return [Hash{String => Array<String>}] Mapping of documentation files to arrays of tracked source files.
+      def load_tracked_files
+        ::DocGuard::Shared::Subprocesses::LoadTrackedFilesFromDocumentation.run(config: config)
+      end
+
+      # Loads stored digests for previously tracked files.
+      #
+      # @return [Hash<String, Hash<String, String>>] Mapping of documentation files to
+      #   tracked file digests (e.g., { "docs/file.md" => { "app/file.rb" => "digest" } }),
+      #   or an empty hash if the file does not exist
+      def load_stored_digests
+        Subprocesses::LoadStoredDigests.run(config: config)
+      end
+
+      # Calculates current digests of tracked files.
+      #
+      # @param tracked_files [Hash<String, Array<String>>] Mapping of documentation files to lists of tracked source file paths.
+      # @return [Hash<String, Hash<String, String?>>] Mapping of documentation files to tracked source files
+      #   and their SHA256 digests (or nil if missing).
+      def calculate_current_digests(tracked_files)
+        ::DocGuard::Shared::Subprocesses::CalculateCurrentDigests.run(tracked_files: tracked_files)
+      end
+
+      # Compares stored and current digests to find mismatches.
+      #
+      # @param stored_digests [Hash<String, Hash<String, String>>] Previously stored digests.
+      # @param current_digests [Hash<String, Hash<String, String?>>] Freshly calculated digests.
+      # @return [Array<String>] List of file paths with mismatched or missing digests.
+      def compare_digests(stored_digests, current_digests)
+        Subprocesses::CompareDigests.run(stored_digests: stored_digests, current_digests: current_digests)
+      end
+
+      # Assesses documentation relevance based on mismatched source files.
+      #
+      # @param tracked_files [Hash{String => Array<String>}] Doc-to-tracked-files mapping.
+      # @param mismatches [Array<String>] list of changed file paths.
+      # @return [Hash{Symbol => Object}]
+      #   - :relevant [Boolean] true if any documentation is outdated.
+      #   - :mismatches [Hash{String => Array<String>}] docs with the changed files they reference.
+      def assess_relevance(tracked_files, mismatches)
+        Subprocesses::AssessRelevance.run(tracked_files: tracked_files, mismatches: mismatches)
+      end
+
+      # Reports the result of the assessment and exits if outdated.
+      #
+      # @param assessment [Hash{Symbol => Object}] Result of the relevance check.
+      # @return [void]
+      def report_assessment(assessment)
+        Subprocesses::ReportAssessment.run(assessment: assessment)
+      end
+    end
+  end
+end

data/lib/doc_guard/assess_documentation_relevance/subprocesses/assess_relevance.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module AssessDocumentationRelevance
+    module Subprocesses
+      # Determines if documentation is outdated based on digest mismatches.
+      #
+      # This subprocess receives a mapping of documentation files to the source files
+      # they describe, and compares that with a list of source files that have changed.
+      # If any documentation file references at least one changed file, it's considered outdated.
+      class AssessRelevance
+        # Assesses which documentation files are outdated based on file digest mismatches.
+        #
+        # @param tracked_files [Hash{String => Array<String>}] Mapping of documentation file paths to the source files they reference.
+        # @param mismatches [Array<String>] List of source files whose digests have changed.
+        #
+        # @return [Hash{Symbol => Object}]
+        #   - :relevant [Boolean] `true` if any documentation files are affected.
+        #   - :mismatches [Hash{String => Array<String>}] Mapping of documentation files to the list of changed source files they reference.
+        def self.run(tracked_files: {}, mismatches: [])
+          documentation_mismatches = tracked_files.each_with_object({}) do |(documentation_file, source_files), acc|
+            changed = source_files.select { |file| mismatches.include?(file) }
+            acc[documentation_file] = changed unless changed.empty?
+          end
+
+          {
+            relevant: documentation_mismatches.any?,
+            mismatches: documentation_mismatches
+          }
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/assess_documentation_relevance/subprocesses/compare_digests.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module AssessDocumentationRelevance
+    module Subprocesses
+      # Compares stored and current file digests per documentation file
+      # to detect which documentation files may now be outdated.
+      class CompareDigests
+        # Returns a list of documentation files where any tracked source file changed.
+        #
+        # @param stored_digests [Hash<String, Hash<String, String>>] Currently mapping of documentation files to tracked source files
+        #   and their SHA256 digests.
+        # @param current_digests [Hash<String, Hash<String, String?>>] New mapping of documentation files to tracked source files
+        #   and their SHA256 digests (or nil if missing).
+        # @return [Array<String>] List of file paths with mismatched or missing digests.
+        def self.run(stored_digests: {}, current_digests: {})
+          (stored_digests.keys | current_digests.keys).each_with_object([]) do |documentation_file, mismatches|
+            stored = stored_digests[documentation_file] || {}
+            current = current_digests[documentation_file] || {}
+
+            (stored.keys | current.keys).each do |source_file|
+              stored[source_file] != current[source_file] ? mismatches.push(source_file) : next
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/assess_documentation_relevance/subprocesses/load_stored_digests.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module AssessDocumentationRelevance
+    module Subprocesses
+      # Loads previously stored digests from a JSON file.
+      class LoadStoredDigests
+        # Runs the subprocess to load stored digests from the configured file path.
+        #
+        # @param config [DocGuard::Config] The configuration containing the path to the digests store.
+        # @return [Hash<String, Hash<String, String>>] Mapping of documentation files to
+        #   tracked file digests (e.g., { "docs/file.md" => { "app/file.rb" => "digest" } }),
+        #   or an empty hash if the file does not exist.
+        def self.run(config: ::DocGuard::Config.new)
+          return {} unless File.exist?(config.digests_store_file_path)
+
+          JSON.parse(File.read(config.digests_store_file_path))
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/assess_documentation_relevance/subprocesses/report_assessment.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module AssessDocumentationRelevance
+    module Subprocesses
+      # Reports the result of the documentation relevance assessment.
+      class ReportAssessment
+        # Outputs the result and exits if documentation is outdated.
+        #
+        # @param assessment [Hash{Symbol => Object}]
+        #   - :relevant [Boolean] Whether documentation is outdated.
+        #   - :mismatches [Hash<String, Array<String>>] Mapping of documentation files to lists of tracked source file paths.
+        # @return [void]
+        def self.run(assessment: {})
+          if assessment[:relevant]
+            warn "‼️ Documentation may be outdated!"
+
+            assessment[:mismatches].each do |documentation_file, changed_files|
+              warn "\n📄 #{documentation_file}"
+              changed_files.each do |file|
+                warn "- #{file}"
+              end
+            end
+
+            exit(1)
+          else
+            puts "✅ Documentation is up to date."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/cli.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DocGuard
+  # Command-line interface for DocGuard.
+  #
+  # Usage:
+  #   doc_guard assess --documentation-path=docs --digests-store-file-path=.digests.json
+  #   doc_guard record
+  #
+  class Cli < Thor
+    class_option :documentation_path, type: :string, desc: "Path to documentation files"
+    class_option :digests_store_file_path, type: :string, desc: "Path to the digests store file"
+    class_option :config_file_path, type: :string, default: ::DocGuard::Config::DEFAULT_CONFIG_FILE_PATH, desc: "Path to the config file"
+
+    desc "assess", "Assess documentation relevance"
+    # @option options [String] :documentation_path Path to documentation files
+    # @option options [String] :digests_store_file_path Path to digests file
+    # @option options [String] :config_file_path Path to config file
+    # @exitstatus 0 if documentation is up to date
+    # @exitstatus 1 if outdated
+    # @exitstatus 2 on errors
+    def assess
+      ::DocGuard::AssessDocumentationRelevance::Process.run(config: build_config_from_options)
+    rescue SystemExit => e
+      exit e.status
+    rescue StandardError => e
+      warn "‼️ Error: #{e.message}"
+      exit 2
+    end
+
+    desc "record", "Record current documentation state"
+    # @option options [String] :documentation_path Path to documentation files
+    # @option options [String] :digests_store_file_path Path to digests file
+    # @option options [String] :config_file_path Path to config file
+    # @exitstatus 0 if success
+    # @exitstatus 1 if failure (e.g. file error)
+    # @exitstatus 2 on errors
+    def record
+      ::DocGuard::RecordDocumentationRelevance::Process.run(config: build_config_from_options)
+    rescue SystemExit => e
+      exit e.status
+    rescue StandardError => e
+      warn "‼️ Error: #{e.message}"
+      exit 2
+    end
+
+    private
+
+    # Builds a configuration object from CLI options.
+    #
+    # @return [DocGuard::Config] The configuration instance initialized with CLI options or defaults.
+    def build_config_from_options
+      ::DocGuard::Config.new(
+        documentation_path: options[:documentation_path],
+        digests_store_file_path: options[:digests_store_file_path],
+        config_file_path: options[:config_file_path]
+      )
+    end
+  end
+end

data/lib/doc_guard/config.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module DocGuard
+  # Handles configuration for DocGuard by loading values from:
+  # - Explicit parameters (highest priority)
+  # - Environment variables
+  # - YAML config file (.doc_guard.yml)
+  # - Internal defaults (lowest priority)
+  #
+  # This class supports usage in CLI, CI/CD pipelines, or manual scripts
+  # without requiring any Rails integration.
+  class Config
+    DEFAULT_CONFIG_FILE_PATH = ".doc_guard.yml"
+    DEFAULT_DIGESTS_STORE_FILE_PATH = ".doc_guard_digests.json"
+    DEFAULT_DOCUMENTATION_PATH = "docs"
+
+    # Initialize configuration for DocGuard.
+    #
+    # You can pass `nil` to `digests_store_file_path` or `documentation_path` to allow fallback to ENV, config file, or defaults.
+    #
+    # @param digests_store_file_path [String, nil] Optional override path for storing digests. Defaults to `.doc_guard_digests.json`.
+    # @param documentation_path [String, nil] Optional override path to the documentation folder. Defaults to `docs`.
+    # @param config_file_path [String, nil] Optional override path to the config file (YAML). Defaults to `.doc_guard.yml`.
+    #
+    # @example Basic usage
+    #   DocGuard::Config.new(
+    #     digests_store_file_path: nil,
+    #     documentation_path: nil
+    #   )
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def initialize(digests_store_file_path: nil, documentation_path: nil, config_file_path: nil)
+      @config_file_path =
+        config_file_path ||
+        ENV["DOC_GUARD_CONFIG_FILE_PATH"] ||
+        DEFAULT_CONFIG_FILE_PATH
+
+      config = load_config_file(@config_file_path)
+
+      @documentation_path =
+        documentation_path ||
+        ENV["DOC_GUARD_DOCUMENTATION_PATH"] ||
+        config["documentation_path"] ||
+        DEFAULT_DOCUMENTATION_PATH
+
+      @digests_store_file_path =
+        digests_store_file_path ||
+        ENV["DOC_GUARD_DIGESTS_STORE_FILE_PATH"] ||
+        config["digests_store_file_path"] ||
+        DEFAULT_DIGESTS_STORE_FILE_PATH
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    # @return [String] Resolved documentation path.
+    attr_reader :documentation_path
+
+    # @return [String] Resolved path to the digests JSON file.
+    attr_reader :digests_store_file_path
+
+    # @return [String] Resolved path to the digests JSON file.
+    attr_reader :config_file_path
+
+    private
+
+    # Loads a YAML config file if it exists, otherwise returns an empty hash.
+    #
+    # @param path [String] Absolute or relative path to the YAML config file.
+    # @return [Hash{String => String}] Parsed YAML contents or empty hash.
+    def load_config_file(config_file_path)
+      if File.exist?(config_file_path)
+        YAML.load_file(config_file_path) || {}
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/doc_guard/record_documentation_relevance/process.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module RecordDocumentationRelevance
+    # Main orchestration class that records the current documentation relevance state
+    # by capturing the latest digests of files referenced in the documentation.
+    class Process
+      # Entry point to run the relevance recording process.
+      #
+      # @param config [DocGuard::Config] Optional configuration.
+      # @return [void]
+      def self.run(config: ::DocGuard::Config.new)
+        new(config: config).call
+      end
+
+      # Initializes the process with the given configuration.
+      #
+      # @param config [DocGuard::Config]
+      def initialize(config: ::DocGuard::Config.new)
+        @config = config
+      end
+
+      # Executes the full relevance recording pipeline.
+      #
+      # @return [void]
+      def call
+        tracked_files = load_tracked_files
+        current_digests = calculate_current_digests(tracked_files)
+        recording = record_digests(current_digests)
+
+        report_recording(recording)
+      end
+
+      private
+
+      attr_reader :config
+
+      # Loads files tracked from documentation annotations.
+      #
+      # @return [Hash{String => Array<String>}] Mapping of documentation files to lists of tracked source file paths.
+      def load_tracked_files
+        ::DocGuard::Shared::Subprocesses::LoadTrackedFilesFromDocumentation.run(config: config)
+      end
+
+      # Calculates current digests of tracked files.
+      #
+      # @param tracked_files [Hash<String, Array<String>>] Mapping of documentation files to lists of tracked source file paths.
+      # @return [Hash<String, Hash<String, String?>>] Mapping of documentation files to tracked source files
+      #   and their SHA256 digests (or nil if missing).
+      def calculate_current_digests(tracked_files)
+        ::DocGuard::Shared::Subprocesses::CalculateCurrentDigests.run(tracked_files: tracked_files)
+      end
+
+      # Records the given digests by saving them to the configured file path.
+      #
+      # @param digests [Hash<String, Hash<String, String?>>] Mapping of documentation files to tracked source files
+      #   and their SHA256 digests (or nil if missing).
+      # @return [Hash{Symbol => Object}] The result hash from the RecordDigests subprocess,
+      #   containing :status and optionally :error keys.
+      def record_digests(digests)
+        Subprocesses::RecordDigests.run(digests: digests, config: config)
+      end
+
+      # Outputs result message to the user.
+      #
+      # @param digests [Hash<String, String>] A map of file paths to their digest strings (current).
+      # @return [void]
+      def report_recording(recording)
+        Subprocesses::ReportRecording.run(recording: recording)
+      end
+    end
+  end
+end

data/lib/doc_guard/record_documentation_relevance/subprocesses/record_digests.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DocGuard
+  module RecordDocumentationRelevance
+    module Subprocesses
+      # Records the current file digests into a configured file path.
+      class RecordDigests
+        # Writes the given digests as pretty-printed JSON to the configured file path.
+        #
+        # @param digests [Hash<String, Hash<String, String?>>] Mapping of documentation files to tracked source files
+        #   and their SHA256 digests (or nil if missing).
+        # @param config [DocGuard::Config] Configuration object with `digests_store_file_path`.
+        # @return [Hash{Symbol => Symbol, Object}] Status result:
+        #   - On success: { status: :ok }
+        #   - On failure: { status: :error, error: error_object }
+        def self.run(digests: {}, config: ::DocGuard::Config.new)
+          File.write(config.digests_store_file_path, JSON.pretty_generate(digests))
+          { status: :ok }
+        rescue StandardError => error
+          { status: :error, error: error }
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/record_documentation_relevance/subprocesses/report_recording.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module RecordDocumentationRelevance
+    module Subprocesses
+      # Outputs a message confirming the result of the documentation state recording.
+      class ReportRecording
+        # Runs the subprocess that reports the result of recording digests.
+        #
+        # @param recording [Hash{Symbol => Symbol, Object}] Status result:
+        #   - On success: { status: :ok }
+        #   - On failure: { status: :error, error: error_object }
+        # @return [void]
+        def self.run(recording: {})
+          case recording[:status]
+          when :ok
+            puts "✅ Documentation state recorded successfully."
+          when :error
+            warn "‼️ Failed to record documentation state: #{recording[:error].message}"
+            exit(1)
+          else
+            warn "⚠️ Unknown recording status."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/shared/subprocesses/calculate_current_digests.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module Shared
+    module Subprocesses
+      # Calculates SHA256 digests for a map of documentation files and their tracked source files.
+      #
+      # Input:
+      # {
+      #   "docs/user.md" => ["app/models/user.rb", "app/services/authenticator.rb"],
+      #   "docs/admin.md" => ["app/models/admin.rb"]
+      # }
+      #
+      # Output:
+      # {
+      #   "docs/user.md" => {
+      #     "app/models/user.rb" => "abcd1234...",
+      #     "app/services/authenticator.rb" => "efgh5678..."
+      #   },
+      #   "docs/admin.md" => {
+      #     "app/models/admin.rb" => nil # file missing
+      #   }
+      # }
+      class CalculateCurrentDigests
+        # Runs the subprocess to calculate SHA256 digests per documentation file and its tracked source files.
+        #
+        # @param tracked_files [Hash<String, Array<String>>] Mapping of documentation files to lists of tracked source file paths.
+        # @return [Hash<String, Hash<String, String?>>] Mapping of documentation files to tracked source files
+        #   and their SHA256 digests (or nil if missing).
+        def self.run(tracked_files: {})
+          tracked_files.transform_values do |source_files|
+            source_files.each_with_object({}) do |file, digest_map|
+              digest_map[file] = File.exist?(file) ? Digest::SHA256.hexdigest(File.read(file)) : nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/shared/subprocesses/load_tracked_files_from_documentation.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DocGuard
+  module Shared
+    module Subprocesses
+      # Loads a mapping between documentation files and the files they track.
+      #
+      # Scans all `.md` files under the configured documentation path,
+      # and builds a map of:
+      #   documentation_file_path => [list of tracked source file paths]
+      #
+      # Example:
+      # {
+      #   "docs/user.md" => ["app/models/user.rb", "app/services/authenticator.rb"],
+      #   "docs/admin.md" => ["app/models/admin.rb"]
+      # }
+      class LoadTrackedFilesFromDocumentation
+        TAG_PATTERN = /<!--\s*doc_guard\s+files:\s*\[(?<files_to_track>[\s\S]*?)\]\s*-->/
+
+        # Builds a hash mapping documentation files to the files they track.
+        #
+        # @param config [DocGuard::Config]
+        # @return [Hash{String => Array<String>}] Mapping of documentation files to lists of tracked source file paths.
+        def self.run(config: ::DocGuard::Config.new)
+          mapping = {}
+
+          Dir.glob("#{config.documentation_path}/**/*.md") do |documentation_file|
+            tracked = []
+
+            content = File.read(documentation_file)
+            content.scan(TAG_PATTERN).each do |match|
+              files = match[0].split(",").map(&:strip)
+              tracked.concat(files)
+            end
+
+            mapping[documentation_file] = tracked.uniq unless tracked.empty?
+          end
+
+          mapping
+        end
+      end
+    end
+  end
+end

data/lib/doc_guard/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module DocGuard
+  # Current version of the DocGuard gem.
+  #
+  # @return [String] The current gem version.
+  VERSION = "1.0.0"
+end

data/lib/doc_guard.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "digest"
+require "json"
+require "thor"
+require "yaml"
+
+# Loads all Ruby files under the DocGuard directory.
+Zeitwerk::Loader.new.tap do |loader|
+  loader.push_dir(File.join(__dir__))
+  loader.setup
+end
+
+# Top-level module for DocGuard gem functionality.
+#
+# @example Raise a custom DocGuard error
+#   raise DocGuard::Error, "something went wrong"
+module DocGuard
+  # Base error class for DocGuard-related exceptions.
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: doc_guard
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Patryk Gramatowski
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-07-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: digest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: |
+  DocGuard helps maintain up-to-date project documentation by tracking files referenced in your docs,
+  calculating file digests, and assessing whether code changes impact your documentation relevance.
+  It provides CLI commands to assess documentation relevance and record the current documentation state,
+  enabling automated enforcement and better documentation quality in Rails and Ruby projects.
+email:
+- patrick.gramatowski@gmail.com
+executables:
+- doc_guard
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- bin/doc_guard
+- doc_guard.gemspec
+- lib/doc_guard.rb
+- lib/doc_guard/assess_documentation_relevance/process.rb
+- lib/doc_guard/assess_documentation_relevance/subprocesses/assess_relevance.rb
+- lib/doc_guard/assess_documentation_relevance/subprocesses/compare_digests.rb
+- lib/doc_guard/assess_documentation_relevance/subprocesses/load_stored_digests.rb
+- lib/doc_guard/assess_documentation_relevance/subprocesses/report_assessment.rb
+- lib/doc_guard/cli.rb
+- lib/doc_guard/config.rb
+- lib/doc_guard/record_documentation_relevance/process.rb
+- lib/doc_guard/record_documentation_relevance/subprocesses/record_digests.rb
+- lib/doc_guard/record_documentation_relevance/subprocesses/report_recording.rb
+- lib/doc_guard/shared/subprocesses/calculate_current_digests.rb
+- lib/doc_guard/shared/subprocesses/load_tracked_files_from_documentation.rb
+- lib/doc_guard/version.rb
+homepage: https://github.com/patrickgramatowski/doc_guard
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/patrickgramatowski/doc_guard
+  source_code_uri: https://github.com/patrickgramatowski/doc_guard
+  changelog_uri: https://github.com/patrickgramatowski/doc_guard/CHANGELOG.md
+post_install_message: "=> ✅ Setup complete! You can now use `doc_guard` on the command
+  line."
+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: 3.4.10
+signing_key:
+specification_version: 4
+summary: DocGuard helps maintain up-to-date project documentation by tracking files
+  referenced in your docs.
+test_files: []