markdown-merge 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9acf350fe99fe21eb039f5b1921b67b3a34f69d02186ca64d5bd48ac73096819
+  data.tar.gz: 87ee2b867a12495e3e5d92ef17b1de91f946757ead984fe03c164921e3b14336
+SHA512:
+  metadata.gz: 787b4f4719021199155ce78bcebfdecb42a33b883a809b1e17f93ffe88c844b007749cd8ceea6c3a9deabe3e0ad8e7dfcd0ffc78a1ced9683cd1a600a9b20693
+  data.tar.gz: 8d4787d8d2f882b51a2bd256da055654f42707c4ace34be07558908434ffced53ecc6d0c1ce2881daf44955e1e92aea7e02284e1ae9091af7316e8dce57946f9

data/CHANGELOG.md

@@ -0,0 +1,251 @@
+# Changelog
+
+[![SemVer 2.0.0][📌semver-img]][📌semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog]
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog][📗keep-changelog],
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+and [yes][📌major-versions-not-sacred], platform and engine support are part of the [public API][📌semver-breaking].
+Please file a bug if you notice a violation of semantic versioning.
+
+[📌semver]: https://semver.org/spec/v2.0.0.html
+[📌semver-img]: https://img.shields.io/badge/semver-2.0.0-FFDD67.svg?style=flat
+[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139
+[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html
+[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
+[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [1.0.0] - 2026-01-19
+
+- TAG: [v1.0.0][1.0.0t]
+- COVERAGE: 91.43% -- 1803/1972 lines in 29 files
+- BRANCH COVERAGE: 79.10% -- 579/732 branches in 29 files
+- 96.92% documented
+
+### Added
+
+- **Cleanse Module**: New namespace for document cleansing/repair utilities
+  - `Cleanse::CondensedLinkRefs` - Fixes condensed link reference definitions caused by previous merge bugs
+    - Parslet-based PEG parser (linear-time, ReDoS-safe) for detecting and expanding `[label]: url[label2]: url2` → separate lines
+    - Detects two corruption patterns: (1) multiple definitions on same line, (2) content before definition without newline
+    - Methods: `#condensed?`, `#expand`, `#definitions`, `#count`
+  - `Cleanse::CodeFenceSpacing` - Fixes malformed code fence language tags
+    - Fixes ` ``` console` → ` ```console` (removes space between backticks and language)
+    - Parslet-based PEG parser (linear-time, ReDoS-safe) for detecting code blocks and their info strings
+    - Supports any indentation level (handles code blocks nested in lists)
+    - Methods: `#malformed?`, `#malformed_count`, `#code_blocks`, `#fix`
+  - `Cleanse::BlockSpacing` - Fixes missing blank lines between block elements
+    - Detects and fixes missing blank lines after thematic breaks (`---`)
+    - Detects and fixes missing blank lines between list items and headings
+    - Detects and fixes missing blank lines between markdown and HTML blocks
+    - Detects and fixes missing blank lines before HTML when preceded by markdown
+    - Special handling for markdown container closing tags (e.g., `</details>`) - adds blank lines before them even when inside HTML blocks, since their content may be markdown
+    - Methods: `#malformed?`, `#issue_count`, `#issues`, `#fix`
+  - **Security Note**: `CondensedLinkRefs` and `CodeFenceSpacing` use PEG parsers instead of regex to eliminate ReDoS vulnerabilities. Both process untrusted Markdown input safely in O(n) time.
+- **LinkParser tree-based nesting detection**:
+  - `#find_all_link_constructs(content)` - Returns tree structure with `:children` for nested items
+  - `#build_link_tree(links, images)` - Detects containment and builds parent-child relationships
+  - `#flatten_leaf_first(items)` - Flattens tree in post-order (children before parents) for safe replacement
+  - Properly handles linked images like `[![alt](img-url)](link-url)` as parent link with child image
+- **`bin/fix_readme_formatting`**: Updated to include `BlockSpacing` cleanse fix
+  - Now fixes missing blank lines between block elements (thematic breaks, lists, headings, HTML)
+  - Runs as Phase 1c after CondensedLinkRefs and CodeFenceSpacing
+- **MergeGemRegistry Integration**: Registers with `Ast::Merge::RSpec::MergeGemRegistry`
+  - Enables automatic RSpec dependency tag support
+  - Registers as category `:markdown` with `skip_instantiation: true` (requires backend)
+- **TestableNode-based spec helpers**: New helper methods using `TreeHaver::RSpec::TestableNode`
+  for creating real node instances in tests instead of fragile mocks
+  - `create_test_node(type, text:, start_line:, ...)` - Create any node type
+  - `create_test_table_node(rows:, text:)` - Create table nodes
+  - `create_test_row_node(cells:, start_line:)` - Create table row nodes
+  - `create_test_cell_node(content:, start_line:)` - Create table cell nodes
+  - `create_test_paragraph_node(content:, start_line:)` - Create paragraph nodes
+  - `create_test_heading_node(level:, content:, start_line:)` - Create heading nodes
+  - `create_test_code_block_node(content:, language:, start_line:)` - Create code block nodes
+  - `create_test_list_node(items:, ordered:, start_line:)` - Create list nodes
+  - `create_test_block_quote_node(content:, start_line:)` - Create block quote nodes
+  - `create_test_thematic_break_node(start_line:)` - Create thematic break nodes
+  - `create_test_html_block_node(content:, start_line:)` - Create HTML block nodes
+- **LinkParser**: New Parslet-based PEG parser for markdown link structures
+  - Properly handles emoji in labels (e.g., `[🖼️galtzo-discord]`)
+  - Handles multi-byte UTF-8 characters without regex limitations
+  - Handles nested brackets (for linked images like `[![alt][ref]](url)`)
+  - Parses link reference definitions: `[label]: url` and `[label]: url "title"`
+  - Parses inline links: `[text](url)` and `[text](url "title")`
+  - Parses inline images: `![alt](url)` and `![alt](url "title")`
+  - Methods: `#parse_definitions`, `#parse_definition_line`, `#find_inline_links`, `#find_inline_images`, `#build_url_to_label_map`
+- **DocumentProblems**: New class for tracking document issues found during merge
+  - Categories: `:duplicate_link_definition`, `:excessive_whitespace`, `:link_has_title`, `:image_has_title`, `:link_ref_spacing`
+  - Severity levels: `:info`, `:warning`, `:error`
+  - Methods: `#add`, `#by_category`, `#by_severity`, `#warnings`, `#errors`, `#infos`, `#merge!`, `#summary_by_category`, `#summary_by_severity`
+  - Accessible via `MergeResult#problems` after merge
+- **WhitespaceNormalizer**: New class for normalizing excessive whitespace
+  - Supports multiple normalization modes:
+    - `:basic` (or `true`) - Collapse excessive blank lines (3+ → 2)
+    - `:link_refs` - Basic + remove blank lines between consecutive link reference definitions
+    - `:strict` - All normalizations (same as :link_refs currently)
+  - Class method: `WhitespaceNormalizer.normalize(content, mode: :basic)`
+  - Instance usage tracks problems for introspection
+  - New `:link_ref_spacing` problem category for tracking removed blank lines between link refs
+- **LinkReferenceRehydrator**: New class for converting inline links to reference style
+  - Converts inline links `[text](url)` to `[text][label]` when matching definition exists
+  - Converts inline images `![alt](url)` to `![alt][label]` when matching definition exists
+  - Skips links/images with titles (would lose title information)
+  - Tracks duplicate definitions and title conflicts in problems
+  - Prefers shortest label when multiple labels point to same URL
+- **SmartMergerBase options**:
+  - `normalize_whitespace: false | true | :basic | :link_refs | :strict` - whitespace normalization mode
+  - `rehydrate_link_references: false` - convert inline links to reference style
+- **PartialTemplateMerger options**:
+  - `normalize_whitespace: false | true | :basic | :link_refs | :strict` - whitespace normalization mode
+  - `rehydrate_link_references: false` - convert inline links to reference style
+- **MergeResult#problems**: Access `DocumentProblems` instance for introspection
+- **OutputBuilder**: New class for building markdown output from merge operations
+  - Consolidates all output assembly logic in one place
+  - Handles node source extraction, link definition reconstruction, gap lines
+  - Replaces manual string concatenation with clean builder pattern
+  - Public methods: `add_node_source`, `add_link_definition`, `add_gap_line`, `add_raw`, `to_s`, `empty?`, `clear`
+- **LinkDefinitionFormatter**: New module for formatting link reference definitions
+  - Reconstructs link definitions that parsers consume during parsing
+  - Methods: `format(node)`, `format_all(nodes)`
+- **Position-based signature generator for PartialTemplateMerger**:
+  - Tables (and other elements) at the same relative position in their sections now match
+  - Fixes the "duplicate tables" bug where tables with different column structures weren't merged
+  - Template table replaces destination table when both are at the same position within the section
+  - Position counters reset for each document, ensuring template and destination tables match
+- **PartialTemplateMerger**: Markdown-specific implementation for partial template merging
+  - Extends `Ast::Merge::PartialTemplateMergerBase` with markdown-specific logic
+  - Heading-level-aware section boundaries (finds next heading of same or higher level)
+  - Source-based text extraction via `analysis.source_range` to preserve:
+    - Link reference definitions (no conversion to inline links)
+    - Table column padding/alignment
+    - Original formatting exactly as written
+  - Supports both Markly and Commonmarker backends via tree_haver
+- **SmartMergerBase**: `add_template_only_nodes` now accepts a callable filter
+  - Boolean `true`/`false` still works as before (add all or none)
+  - Callable (Proc/Lambda) receives `(node, entry)` and returns truthy to add the node
+  - Enables selective addition of template-only nodes based on signature, type, or content
+  - Useful for partial template merging where only specific template nodes should be added
+
+### Changed
+
+- Upgrade to [ast-merge v4.0.2](https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.2)
+- Upgrade to [tree_haver v5.0.2](https://github.com/kettle-rb/tree_haver/releases/tag/v5.0.2)
+- **WhitespaceNormalizer refactored to use LinkParser**
+  - Removed `LINK_REF_PATTERN` regex constant
+  - Now uses `LinkParser#parse_definition_line` for link definition detection
+  - Supports all link definition formats that LinkParser handles:
+    - Angle-bracketed URLs: `[label]: <url>`
+    - Emoji in labels: `[🎨logo]: url`
+    - Definitions with titles in any quote style
+  - Completely regex-free implementation
+- **LinkDefinitionNode**: Now uses `LinkParser` (Parslet-based) instead of regex for parsing
+  - Properly handles emoji in labels (e.g., `[🖼️galtzo-discord]`)
+  - More robust parsing of multi-byte UTF-8 characters
+- **LinkReferenceRehydrator**: Rewritten to use `LinkParser` (Parslet-based) for all parsing
+  - Uses `LinkParser#parse_definitions` to parse link reference definitions
+  - Uses `LinkParser#find_inline_links` and `#find_inline_images` to find inline constructs
+  - Properly handles linked images (e.g., `[![alt][ref]](url)`)
+  - Properly handles emoji in link text and URLs
+  - No regex used - all parsing via PEG grammar
+- **PartialTemplateMerger#find_section_end**: For headings, now always uses heading-level-aware logic, ignoring tree-depth-based boundary from `InjectionPointFinder`
+  - Fixes duplicate H4 section bug where nested headings (e.g., H4 inside H3) were incorrectly treated as section boundaries
+  - In Markdown, all headings are siblings at the same tree depth regardless of level (H2, H3, H4), so tree depth cannot determine section boundaries
+  - Heading level semantics require comparing actual heading level numbers (H3 < H4 means H4 is nested)
+- **SmartMergerBase**: Refactored to use OutputBuilder throughout
+  - `process_alignment` now returns OutputBuilder instead of array
+  - New methods: `process_match_to_builder`, `process_template_only_to_builder`, `process_dest_only_to_builder`
+  - Old methods deprecated but kept for compatibility
+  - Inner merge for code blocks now uses `try_inner_merge_code_block_to_builder`
+- **OutputBuilder**: Enhanced node extraction to handle `source_position` method
+  - Supports nodes with `source_position` hash
+  - Falls back to `to_commonmark` if position unavailable
+  - Handles FreezeNode, LinkDefinitionNode, GapLineNode, and parser nodes
+- **FileAnalysisBase**: Added `@errors` instance variable and `errors` attr_reader
+  - `valid?` now checks both `@errors.empty?` and `!@document.nil?`
+  - Consistent with bash-merge, json-merge, jsonc-merge, and toml-merge patterns
+- **FileAnalysis error handling**: Now rescues `TreeHaver::Error` in `parse_document`
+  - `TreeHaver::Error` inherits from `Exception`, not `StandardError`
+  - `TreeHaver::NotAvailable` is a subclass of `TreeHaver::Error`, so it's also caught
+  - Stores error in `@errors` and returns nil, so `valid?` returns false
+  - `SmartMergerBase#parse_and_analyze` then raises the appropriate parse error
+- **Dependency tags**: Refactored to use shared `TreeHaver::RSpec::DependencyTags` from tree_haver gem
+  - All dependency detection is now centralized in tree_haver
+  - Use `require "tree_haver/rspec"` for shared RSpec configuration
+  - `MarkdownMergeDependencies` is now an alias to `TreeHaver::RSpec::DependencyTags`
+  - Enables `MARKDOWN_MERGE_DEBUG=1` for dependency summary output
+  - Inner-merge dependencies (`:toml_merge`, `:json_merge`, `:prism_merge`, `:psych_merge`) now available
+- **CodeBlockMerger**: Refactored class methods to remove redundant error handling
+  - Removed duplicate `rescue` blocks from `merge_with_prism`, `merge_with_psych`, `merge_with_json`, `merge_with_toml`
+  - Error handling is now consolidated in `merge_code_blocks` instance method
+  - Class methods now raise exceptions which are caught by `merge_code_blocks`
+  - Updated specs to test through `merge_code_blocks` (the intended API) instead of class methods directly
+
+### Fixed
+
+- **CondensedLinkRefs false positive**: Fixed bug where reference-style links followed by colon
+  (e.g., `**[Floss-Funding.dev][🖇floss-funding.dev]:**`) were incorrectly detected as condensed
+  link reference definitions
+  - The pattern `][label]:` was matching, but this is a reference link with punctuation, not a link def
+  - Now requires URL-like content after `]:` to confirm it's a real link def
+  - Supports both full URLs (`https://...`) and relative paths (`CONTRIBUTING.md`, `LICENSE.txt`)
+  - The relative path pattern matches `UPPERCASE.ext` format common in repo files
+  - Prevents incorrect newline insertion inside markdown links
+- **LinkReferenceRehydrator content corruption**: Fixed critical bug where rehydrating linked images
+  like `[![alt](img-url)](link-url)` would corrupt document content
+  - The parser was finding both the outer link and inner image as separate items
+  - Replacing both overlapping items corrupted the content, losing significant portions of documents
+  - Now uses tree-based approach: builds parent-child relationships for nested constructs
+  - Processes replacements recursively: children are processed first, then parent text is updated
+    to include child replacements before parent is processed
+  - Single pass now handles all nested structures (no more multi-pass workaround needed)
+  - Test fixture showed 68 lines lost (1023 → 955) before fix, now preserves all content
+- **OutputBuilder**: Fixed link definitions being concatenated without newlines
+  - `extract_source` for `LinkDefinitionNode` now includes trailing newline
+  - Link definitions are now properly output on separate lines
+- **OutputBuilder**: Fixed auto-spacing to properly handle link_definition transitions
+  - Removed `link_definition` from the skip list for auto-spacing
+  - Now correctly adds blank lines when transitioning FROM link_definition TO other content (e.g., headings)
+  - `MarkdownStructure.needs_blank_between?` now handles contiguous types properly
+- **MarkdownStructure**: Added support for contiguous node types
+  - New `CONTIGUOUS_TYPES` constant for node types that should not have blank lines between consecutive instances
+  - `link_definition` is now a contiguous type - consecutive link definitions won't have blank lines inserted
+  - Added `link_definition` to `NEEDS_BLANK_AFTER` - link definition blocks get blank line after when followed by other content
+  - New `contiguous_type?` method to check if a type is contiguous
+  - `needs_blank_between?` now returns `false` for consecutive nodes of the same contiguous type
+- **PartialTemplateMerger#node_to_text**: Fixed double blank line bug
+  - `source_range` already adds trailing newlines, so adding another `"\n"` caused double blank lines
+  - Removed the extra `+ "\n"` that was causing excessive blank lines in merged output
+- **Lint cleanup**: Fixed RSpec/ReceiveMessages cops by combining multiple `receive` stubs
+- **Style fixes**: Fixed Style/ClassMethodsDefinitions in `LinkDefinitionNode` using `class << self`
+- **Layout fixes**: Removed extra blank lines in `mock_helpers.rb`
+- **Freeze block detection**: Fixed `find_freeze_markers` to handle both raw parser types
+  (`:html`) and TreeHaver normalized types (`"html_block"`, `:html_block`). Previously,
+  freeze markers were not detected when using TreeHaver backends because the node type
+  check only looked for `:html`.
+- **Freeze marker content extraction**: Now uses a three-tier fallback for extracting
+  HTML comment content:
+  1. `string_content` (raw Markly/Commonmarker nodes)
+  2. `to_commonmark` on the wrapper node
+  3. `inner_node.to_commonmark` (TreeHaver Commonmarker wrapper)
+  This fixes freeze block detection for Commonmarker where the TreeHaver wrapper's
+  content methods return empty but the inner node has the actual content.
+
+[Unreleased]: https://github.com/kettle-rb/markdown-merge/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/kettle-rb/markdown-merge/compare/76f2230840b236dd10fdd7baf322c082762dddb0...v1.0.0
+[1.0.0t]: https://github.com/kettle-rb/markdown-merge/tags/v1.0.0

data/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+title: markdown-merge
+message: >-
+  If you use this work and you want to cite it,
+  then you can use the metadata from this file.
+type: software
+authors:
+  - given-names: Peter Hurn
+    family-names: Boling
+    email: peter@railsbling.com
+    affiliation: railsbling.com
+    orcid: 'https://orcid.org/0009-0008-8519-441X'
+identifiers:
+  - type: url
+    value: 'https://github.com/kettle-rb/markdown-merge'
+    description: markdown-merge
+repository-code: 'https://github.com/kettle-rb/markdown-merge'
+abstract: >-
+  markdown-merge
+license: See license file

data/CODE_OF_CONDUCT.md

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

data/CONTRIBUTING.md

@@ -0,0 +1,227 @@
+# Contributing
+
+Bug reports and pull requests are welcome on [CodeBerg][📜src-cb], [GitLab][📜src-gl], or [GitHub][📜src-gh].
+This project should be a safe, welcoming space for collaboration, so contributors agree to adhere to
+the [code of conduct][🤝conduct].
+
+To submit a patch, please fork the project, create a patch with tests, and send a pull request.
+
+Remember to [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] if you make changes.
+
+## Help out!
+
+Take a look at the `reek` list which is the file called `REEK` and find something to improve.
+
+Follow these instructions:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b my-new-feature`)
+3. Make some fixes.
+4. Commit changes (`git commit -am 'Added some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Make sure to add tests for it. This is important, so it doesn't break in a future release.
+7. Create new Pull Request.
+
+## Executables vs Rake tasks
+
+Executables shipped by dependencies, such as kettle-dev, and stone_checksums, are available
+after running `bin/setup`. These include:
+
+- gem_checksums
+- kettle-changelog
+- kettle-commit-msg
+- kettle-dev-setup
+- kettle-dvcs
+- kettle-pre-release
+- kettle-readme-backers
+- kettle-release
+
+There are many Rake tasks available as well. You can see them by running:
+
+```shell
+bin/rake -T
+```
+
+## Environment Variables for Local Development
+
+Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable.
+
+General/runtime
+- DEBUG: Enable extra internal logging for this library (default: false)
+- REQUIRE_BENCH: Enable `require_bench` to profile requires (default: false)
+- CI: When set to true, adjusts default rake tasks toward CI behavior
+
+Coverage (kettle-soup-cover / SimpleCov)
+- K_SOUP_COV_DO: Enable coverage collection (default: true in .envrc)
+- K_SOUP_COV_FORMATTERS: Comma-separated list of formatters (html, xml, rcov, lcov, json, tty)
+- K_SOUP_COV_MIN_LINE: Minimum line coverage threshold (integer, e.g., 100)
+- K_SOUP_COV_MIN_BRANCH: Minimum branch coverage threshold (integer, e.g., 100)
+- K_SOUP_COV_MIN_HARD: Fail the run if thresholds are not met (true/false)
+- K_SOUP_COV_MULTI_FORMATTERS: Enable multiple formatters at once (true/false)
+- K_SOUP_COV_OPEN_BIN: Path to browser opener for HTML (empty disables auto-open)
+- MAX_ROWS: Limit console output rows for simplecov-console (e.g., 1)
+  Tip: When running a single spec file locally, you may want `K_SOUP_COV_MIN_HARD=false` to avoid failing thresholds for a partial run.
+
+GitHub API and CI helpers
+- GITHUB_TOKEN or GH_TOKEN: Token used by `ci:act` and release workflow checks to query GitHub Actions status at higher rate limits
+
+Releasing and signing
+- SKIP_GEM_SIGNING: If set, skip gem signing during build/release
+- GEM_CERT_USER: Username for selecting your public cert in `certs/<USER>.pem` (defaults to $USER)
+- SOURCE_DATE_EPOCH: Reproducible build timestamp.
+  - `kettle-release` will set this automatically for the session.
+  - Not needed on bundler >= 2.7.0, as reproducible builds have become the default.
+
+Git hooks and commit message helpers (exe/kettle-commit-msg)
+- GIT_HOOK_BRANCH_VALIDATE: Branch name validation mode (e.g., `jira`) or `false` to disable
+- GIT_HOOK_FOOTER_APPEND: Append a footer to commit messages when goalie allows (true/false)
+- GIT_HOOK_FOOTER_SENTINEL: Required when footer append is enabled — a unique first-line sentinel to prevent duplicates
+- GIT_HOOK_FOOTER_APPEND_DEBUG: Extra debug output in the footer template (true/false)
+
+For a quick starting point, this repository’s `.envrc` shows sane defaults, and `.env.local` can override them locally.
+
+## Appraisals
+
+From time to time the [appraisal2][🚎appraisal2] gemfiles in `gemfiles/` will need to be updated.
+They are created and updated with the commands:
+
+```console
+bin/rake appraisal:update
+```
+
+If you need to reset all gemfiles/*.gemfile.lock files:
+
+```console
+bin/rake appraisal:reset
+```
+
+When adding an appraisal to CI, check the [runner tool cache][🏃‍♂️runner-tool-cache] to see which runner to use.
+
+## The Reek List
+
+Take a look at the `reek` list which is the file called `REEK` and find something to improve.
+
+To refresh the `reek` list:
+
+```console
+bundle exec reek > REEK
+```
+
+## Run Tests
+
+To run all tests
+
+```console
+bundle exec rake test
+```
+
+### Spec organization (required)
+
+- One spec file per class/module. For each class or module under `lib/`, keep all of its unit tests in a single spec file under `spec/` that mirrors the path and file name exactly: `lib/markdown/merge/my_class.rb` -> `spec/markdown/merge/my_class_spec.rb`.
+- Exception: Integration specs that intentionally span multiple classes. Place these under `spec/integration/` (or a clearly named integration folder), and do not directly mirror a single class. Name them after the scenario, not a class.
+
+## Lint It
+
+Run all the default tasks, which includes running the gradually autocorrecting linter, `rubocop-gradual`.
+
+```console
+bundle exec rake
+```
+
+Or just run the linter.
+
+```console
+bundle exec rake rubocop_gradual:autocorrect
+```
+
+For more detailed information about using RuboCop in this project, please see the [RUBOCOP.md](RUBOCOP.md) guide. This project uses `rubocop_gradual` instead of vanilla RuboCop, which requires specific commands for checking violations.
+
+### Important: Do not add inline RuboCop disables
+
+Never add `# rubocop:disable ...` / `# rubocop:enable ...` comments to code or specs (except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). Instead:
+
+- Prefer configuration-based exclusions when a rule should not apply to certain paths or files (e.g., via `.rubocop.yml`).
+- When a violation is temporary, and you plan to fix it later, record it in `.rubocop_gradual.lock` using the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred)
+  - `bundle exec rake rubocop_gradual:force_update` (only when you cannot fix the violations immediately)
+
+As a general rule, fix style issues rather than ignoring them. For example, our specs should follow RSpec conventions like using `described_class` for the class under test.
+
+## Contributors
+
+Your picture could be here!
+
+[![Contributors][🖐contributors-img]][🖐contributors]
+
+Made with [contributors-img][🖐contrib-rocks].
+
+Also see GitLab Contributors: [https://gitlab.com/kettle-rb/markdown-merge/-/graphs/main][🚎contributors-gl]
+
+## For Maintainers
+
+### One-time, Per-maintainer, Setup
+
+**IMPORTANT**: To sign a build,
+a public key for signing gems will need to be picked up by the line in the
+`gemspec` defining the `spec.cert_chain` (check the relevant ENV variables there).
+All releases are signed releases.
+See: [RubyGems Security Guide][🔒️rubygems-security-guide]
+
+NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in the environment.
+
+### To release a new version:
+
+#### Automated process
+
+1. Update version.rb to contain the correct version-to-be-released.
+2. Run `bundle exec kettle-changelog`.
+3. Run `bundle exec kettle-release`.
+4. Stay awake and monitor the release process for any errors, and answer any prompts.
+
+#### Manual process
+
+1. Run `bin/setup && bin/rake` as a "test, coverage, & linting" sanity check
+2. Update the version number in `version.rb`, and ensure `CHANGELOG.md` reflects changes
+3. Run `bin/setup && bin/rake` again as a secondary check, and to update `Gemfile.lock`
+4. Run `git commit -am "🔖 Prepare release v<VERSION>"` to commit the changes
+5. Run `git push` to trigger the final CI pipeline before release, and merge PRs
+    - NOTE: Remember to [check the build][🧪build].
+6. Run `export GIT_TRUNK_BRANCH_NAME="$(git remote show origin | grep 'HEAD branch' | cut -d ' ' -f5)" && echo $GIT_TRUNK_BRANCH_NAME`
+7. Run `git checkout $GIT_TRUNK_BRANCH_NAME`
+8. Run `git pull origin $GIT_TRUNK_BRANCH_NAME` to ensure latest trunk code
+9. Optional for older Bundler (< 2.7.0): Set `SOURCE_DATE_EPOCH` so `rake build` and `rake release` use the same timestamp and generate the same checksums
+    - If your Bundler is >= 2.7.0, you can skip this; builds are reproducible by default.
+    - Run `export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH`
+    - If the echo above has no output, then it didn't work.
+    - Note: `zsh/datetime` module is needed, if running `zsh`.
+    - In older versions of `bash` you can use `date +%s` instead, i.e. `export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH`
+10. Run `bundle exec rake build`
+11. Run `bin/gem_checksums` (more context [1][🔒️rubygems-checksums-pr], [2][🔒️rubygems-guides-pr])
+    to create SHA-256 and SHA-512 checksums. This functionality is provided by the `stone_checksums`
+    [gem][💎stone_checksums].
+    - The script automatically commits but does not push the checksums
+12. Sanity check the SHA256, comparing with the output from the `bin/gem_checksums` command:
+    - `sha256sum pkg/<gem name>-<version>.gem`
+13. Run `bundle exec rake release` which will create a git tag for the version,
+    push git commits and tags, and push the `.gem` file to the gem host configured in the gemspec.
+
+[📜src-gl]: https://gitlab.com/kettle-rb/markdown-merge/
+[📜src-cb]: https://codeberg.org/kettle-rb/markdown-merge
+[📜src-gh]: https://github.com/kettle-rb/markdown-merge
+[🧪build]: https://github.com/kettle-rb/markdown-merge/actions
+[🤝conduct]: https://gitlab.com/kettle-rb/markdown-merge/-/blob/main/CODE_OF_CONDUCT.md
+[🖐contrib-rocks]: https://contrib.rocks
+[🖐contributors]: https://github.com/kettle-rb/markdown-merge/graphs/contributors
+[🚎contributors-gl]: https://gitlab.com/kettle-rb/markdown-merge/-/graphs/main
+[🖐contributors-img]: https://contrib.rocks/image?repo=kettle-rb/markdown-merge
+[💎gem-coop]: https://gem.coop
+[🔒️rubygems-security-guide]: https://guides.rubygems.org/security/#building-gems
+[🔒️rubygems-checksums-pr]: https://github.com/rubygems/rubygems/pull/6022
+[🔒️rubygems-guides-pr]: https://github.com/rubygems/guides/pull/325
+[💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums
+[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
+[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat
+[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139
+[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html
+[🚎appraisal2]: https://github.com/appraisal-rb/appraisal2
+[🏃‍♂️runner-tool-cache]: https://github.com/ruby/ruby-builder/releases/tag/toolcache