rubocop-prose 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df5161ee5df2bb5e5b642b3baefb5f95ec038cea286de98c177c317af2ed8115
-  data.tar.gz: 2dde6ed1646ce551227eed6465856616056972e520ccc2830d65c2e035b7d74f
+  metadata.gz: 5b1db83138f25023651073aac3d37c15e31d5d4c5215240eee8ce6643c597142
+  data.tar.gz: 850c71239710eb866e74a303bf4c48d8841b3106af32a6e8ae5ed5a7e66ac709
 SHA512:
-  metadata.gz: dcd9ff6b678a0ddcb11c07ec164a5f047f333bd656afe88f0f36eb80fac561c83ef5014de712ee08f212ea2a3f3cb1a291ee76ec70b8078462296538ba119b57
-  data.tar.gz: 52279ff43345beeda93aebd8b718c66a5dc2dea1fcc801c9aab57a4ba467f0ae1d52d4ef1d180d128fc5c8cca9d5153e694980a05984f91583ea7080b9b73fdd
+  metadata.gz: 791f01d9d94227460b00b302869b68dc00a93e1f812920bb2d3854b62336cc51ec82a75048d8bcb57ca0eb4a2beb66a2abfc883614ecc7fc4de34b0b9de6cf82
+  data.tar.gz: 024d78fe0f8fb6f5189781df28c4421d203416f9fb18453b404e846dea087ba846a18b505614877f173a998b1bf7ee7164d1bf9f083bed480878c626a09ba243

data/AGENTS.md

@@ -1,13 +1,21 @@
-# Contributor instructions
+# Contributor Instructions
 
 Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests, and pull-request conventions. Read [DESIGN.md](DESIGN.md) before changing parsing, source mapping, or correction behavior.
 
 Keep user guidance in the README and cop guides, contributor workflow in CONTRIBUTING, architecture and rationale in DESIGN, and this file focused on high-value agent guidance. Link to the authoritative documentation instead of duplicating it.
 
+Migration documentation must identify the source released version, for example `Migrating From 0.1.0`, rather than using generic “Migration” or “earlier versions” wording. Put migration sections last in cop guides, after configuration and all good/bad examples. Keep them focused on required configuration changes and examples, without explaining validation machinery or restating unchanged settings. Do not describe unreleased schema iterations as migrations.
+
+Verify each configuration migration once with a focused unit test of its RuboCop migration rule. Do not add integration tests for obsolete configurations; keep integration coverage focused on supported configuration and cop behavior.
+
+Update DESIGN only for new architectural decisions or non-obvious invariants not already covered there. Do not add per-cop implementation summaries or repeat configuration behavior from cop guides; ordinary feature changes usually need no DESIGN update.
+
 Preserve original source buffers and character-based locations, Markdown container prefixes and hard breaks, and atomic inline syntax. Plain text must remain literal; format-specific cops must not inspect the other format. Withhold corrections when a safe rewrite cannot be established.
 
 Keep common cleanup enabled by default and project-specific, editorial, or renderer-dependent policies opt-in. Do not add an external preprocessor dependency. Preserve functional dependency loading and compatibility settings.
 
 When adding a cop, follow the checklist in [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-cop); document its user-visible behavior and meaningful limits without repeating shared exclusions.
 
-Do not edit historical changelog entries or add one for documentation, tooling, refactoring, or unreleased functionality. Preserve the vendored helmet SVG and its license; follow CONTRIBUTING for artwork changes.
+Enable new cops in this repository's `.rubocop.yml` and include applicable self-linting changes in the feature PR so reviewers can see their effect. Keep the distributed default independent: editorial policies remain opt-in for users.
+
+Do not edit historical changelog entries or add one for documentation, tooling, refactoring, or unreleased functionality. Keep `- Your contribution here.` at the end of the `(Next)` changelog change list without a blank line above it; remove it only when preparing that version for release. Preserve the vendored helmet SVG and its license; follow CONTRIBUTING for artwork changes.

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.0 (2026/11/06)
+
+- [#126](https://github.com/dblock/rubocop-prose/pull/126): Report unit and integration test coverage to Coveralls - [@dblock](https://github.com/dblock).
+- [#138](https://github.com/dblock/rubocop-prose/pull/138): Add opt-in `Markdown/ListItemPunctuation` to check punctuation presence across sibling list items - [@dblock](https://github.com/dblock).
+- [#139](https://github.com/dblock/rubocop-prose/pull/139): Add an opt-in exception for a single trailing space on empty Markdown blockquote lines, including nested quotes - [@dblock](https://github.com/dblock).
+- [#140](https://github.com/dblock/rubocop-prose/pull/140): Add per-element attribute allowlists to `Markdown/RawHtml` - [@dblock](https://github.com/dblock).
+- [#141](https://github.com/dblock/rubocop-prose/pull/141): Add opt-in `Markdown/HeadingCapitalization` with title-case and initial-capital styles and unsafe autocorrection - [@dblock](https://github.com/dblock).
+- [#142](https://github.com/dblock/rubocop-prose/pull/142): Add opt-in `Markdown/ListItemCapitalization` with consistent, initial-capital, and title-case styles and unsafe autocorrection - [@dblock](https://github.com/dblock).
+- [#143](https://github.com/dblock/rubocop-prose/pull/143): Add default-enabled YAML syntax diagnostics for closed leading Markdown front matter - [@dblock](https://github.com/dblock).
+- [#145](https://github.com/dblock/rubocop-prose/pull/145): Add opt-in `Markdown/FrontMatterKeys` for allowed and required top-level YAML metadata keys - [@dblock](https://github.com/dblock).
+- [#146](https://github.com/dblock/rubocop-prose/pull/146): Add aligned list marker spacing with configurable minimum padding; breaking configuration change: replace the four `Single`/`Multi` spacing options with shared `EnforcedStyle` and `MinSpaces` settings - [@dblock](https://github.com/dblock).
+- [#148](https://github.com/dblock/rubocop-prose/pull/148): Add opt-in `Prose/SentenceCapitalization` for Markdown and plain-text paragraph openings, reporting literal lowercase terms without autocorrecting them - [@dblock](https://github.com/dblock).
+- [#149](https://github.com/dblock/rubocop-prose/pull/149): Add `Text/ProperNames` and `Text/HardTabs` for literal plain text alongside their Markdown counterparts - [@dblock](https://github.com/dblock).
+- [#150](https://github.com/dblock/rubocop-prose/pull/150): Support per-level document, sibling, or disabled duplicate-heading scopes with range and comparison selectors - [@dblock](https://github.com/dblock).
+- [#151](https://github.com/dblock/rubocop-prose/pull/151): Simplify `Markdown/StructuralLineLength` to per-element widths or `false`, remove shared and paired settings, and add migration diagnostics - [@dblock](https://github.com/dblock).
+- [#152](https://github.com/dblock/rubocop-prose/pull/152): Simplify `Markdown/ReferenceDefinitions` configuration; breaking change: replace `CheckDuplicates` and `AllowIdenticalDuplicates` with `Duplicates: forbid | allow_identical | allow`, and rename `CheckUnused` to `Unused`, with migration diagnostics - [@dblock](https://github.com/dblock).
+- [#153](https://github.com/dblock/rubocop-prose/pull/153): Simplify `Markdown/FirstHeading` front-matter configuration; replace `FrontMatterTitle: true` and `TitleKey` with the metadata key in `FrontMatterTitle` - [@dblock](https://github.com/dblock).
+- [#154](https://github.com/dblock/rubocop-prose/pull/154): Standardize Markdown cop style settings on `Style`, migrating released `EnforcedStyle` keys - [@dblock](https://github.com/dblock).
+- [#159](https://github.com/dblock/rubocop-prose/pull/159): Support RuboCop-md 3.0.0; rename `Markdown/Syntax` to `Markdown/KramdownSyntax` to avoid its upstream cop-name collision - [@dblock](https://github.com/dblock).
+
 ## 0.1.0 (2026/11/03)
 
 - [#120](https://github.com/dblock/rubocop-prose/pull/120): Add a default-enabled Markdown hard-break style policy with backslash and trailing-space syntax options - [@dblock](https://github.com/dblock).

data/CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing
 
-## Setup and validation
+## Setup and Validation
 
 Use Ruby 3.2 or newer. Supported RuboCop versions are 1.72.1 and newer within 1.x.
 
@@ -14,13 +14,19 @@ The default Rake task runs RuboCop and the full test suite. For focused changes,
 
 CI covers Ruby 3.2 and 4.0, gem packaging, and optional Markdown-preprocessor interoperability. See the [workflows](.github/workflows) for suite selection and dependency versions.
 
-The lint configuration loads this checkout's plugin alongside rubocop-rspec and rubocop-rake; intentionally invalid fixtures are excluded.
+Run `COVERAGE=true bundle exec rake spec` to generate an HTML report in `coverage/` and `coverage/.resultset.json` for Coveralls. CI combines the Ruby 4.0 unit and standalone integration reports on [Coveralls](https://coveralls.io/github/dblock/rubocop-prose); subprocess smoke tests and optional interoperability are not instrumented.
+
+The lint configuration loads this checkout's plugin alongside `rubocop-rspec` and `rubocop-rake`; intentionally invalid fixtures are excluded.
+
+The repository also enables applicable opt-in prose cops for self-linting without changing their distributed defaults. `Markdown/HeadingStructure` stays disabled because documents do not share an exact outline. `Markdown/StructuralLineLength` limits headings to 120 columns, not code samples or tables. Raw HTML is limited to images with `src`, `alt`, and `width` attributes for the README artwork; the README is exempt from `Markdown/FirstHeading` to preserve its leading logo.
 
 ### Benchmarks
 
 Run `bundle exec rake benchmark`; set `ITERATIONS` and `SECTIONS` to override sample counts and corpus sizes, for example `ITERATIONS=5 SECTIONS=10,50,100 bundle exec rake benchmark`.
 
-The benchmark compares document analysis, cop investigation, and in-memory autocorrection on Markdown and text corpora. Each operation constructs a fresh document; compare results only across revisions using the same Ruby, RuboCop, and corpus settings. Timings are machine-dependent, not CI thresholds.
+The benchmark compares document analysis, cop investigation, and in-memory autocorrection on Markdown and text corpora, using both distributed defaults and this repository's configuration (`default` and `project` profiles). The corpora include Unicode, front matter, references, tables, code, multi-digit lists, capitalization, proper names, and hard tabs. Each operation constructs a fresh document; compare results only across revisions using the same Ruby, RuboCop, corpus, and profile settings. Output fingerprints verify stable diagnostics and corrections across iterations. Timings are machine-dependent, not CI thresholds.
+
+The `document/markdown` operation measures the basic AST and paragraph source mapping; `analysis/markdown` also exercises link/reference scanning, table cells, and positioned emphasis independently of cop execution.
 
 ## Tests
 
@@ -28,19 +34,21 @@ Keep focused cop tests in `spec/<name>_spec.rb`. Cover offenses, exclusions, Uni
 
 Exercise the real CLI when changing plugin loading, stdin, suppression directives, or cross-cop corrections. Test both CLI-option and YAML plugin loading. Interoperability changes also need both preprocessor loading orders, simultaneous prose/Ruby corrections, repeated runs, and stdin.
 
-### Integration fixtures
+### Integration Fixtures
 
 Scenarios live under `spec/fixtures/{prose,markdown,text,markdown_interoperability}/`, with specs in `spec/integration/` and `spec/interoperability/`. Each contains an `input` document, a `case.yml` declaring `offenses` and `remaining_offenses` counts (empty maps for clean results), and an `expected` document when correction changes the input.
 
 Content fixtures call `RuboCop::CLI` in-process with fresh configuration state, checking explicit files, discovery, corrections, repeated runs, and stdin with both plugin-loading configurations. Fixtures with explicit `Enabled: true` cop entries run with `--only`; others exercise configured defaults. Mark whitespace-sensitive fixtures using the existing Git attributes.
 
+Set `unsafe_autocorrect: true` in `case.yml` for fixtures that require `-A` instead of safe autocorrection.
+
 Fresh-process smoke tests in `spec/integration/cli_spec.rb` check YAML and CLI-option plugin boot for Markdown and text, standard and custom-extension discovery, stdin without disk mutation, and stable corrections. Interoperability keeps a combined Ruby/Markdown scenario across both loading orders and plugin-loading mechanisms; edge cases check reporting, correction, and stability under both loading orders using YAML plugin loading.
 
 Mixed default-cop scenarios in `spec/fixtures/markdown_stability/` check content and document structure after every correction, convergence without cycles, and byte-identical output after stabilization.
 
-For optional interoperability, set `RUBOCOP_MD_PATH` to a checkout supporting the [original-buffer mapping API](DESIGN.md#preprocessor-interoperability) and run `bundle exec rake spec:interoperability`. Without that variable, the suite is skipped. Its separate CI workflow runs only on Ruby 4.0; update the rubocop-md ref when the required API is released.
+For optional interoperability, set `RUBOCOP_MD_PATH` to a `rubocop-md` checkout at `v3.0.0` and run `bundle exec rake spec:interoperability`. This release provides the [original-buffer mapping API](DESIGN.md#preprocessor-interoperability). Without that variable, the suite is skipped. Its separate CI workflow runs only on Ruby 4.0 and pins the same released tag.
 
-## Adding a cop
+## Adding a Cop
 
 Add implementations under `lib/rubocop/cop/prose`, `lib/rubocop/cop/markdown`, or `lib/rubocop/cop/text`, inheriting from the corresponding department `Base`. Add a per-cop YAML file under `config/cops/<department>/` with an explicit `Enabled` value, supported options, correction policy, and applicable file patterns. The loader discovers implementations and merges their configuration files.
 
@@ -48,12 +56,14 @@ Add focused specs, a guide under `docs/cops/<department>/` with complete default
 
 Validate defaults, packaging, and the affected tests. Enable broadly applicable cleanup by default; keep project-specific, editorial, and renderer-dependent policies opt-in. Preserve functional dependency loading and compatibility CI settings.
 
-## Pull requests
+## Pull Requests
 
 See [RELEASING.md](RELEASING.md) for the maintainer release procedure.
 
 Keep each pull request focused, with one coherent commit, and use squash merges. Include behavior and configuration documentation. Preserve unrelated worktree changes.
 
+For breaking changes, add a one-line migration summary to [UPGRADING](UPGRADING.md) under the target release, linking to the detailed cop guide. Describe only net changes since the source released version, not unreleased configuration iterations.
+
 Add a linked unreleased changelog entry only for a notable user-facing change, using the actual pull-request number. Do not add entries for documentation, tooling, refactoring, or unreleased functionality; update an existing feature entry when appropriate.
 
 ```markdown

data/DESIGN.md

@@ -1,6 +1,6 @@
 # Design
 
-## Scope and file selection
+## Scope and File Selection
 
 The plugin checks Markdown and plain-text prose without evaluating Ruby snippets. `Prose/*` policies apply to both formats; `Markdown/*` and `Text/*` are format-specific. Common cleanup is enabled by default, while project-specific, editorial, and renderer-dependent policies remain opt-in. User-visible behavior and defaults are in [the README cops catalog](README.md#cops) and the cop guides.
 
@@ -8,7 +8,7 @@ The plugin checks Markdown and plain-text prose without evaluating Ruby snippets
 
 The plugin loads document support and abstract cop bases before concrete cops, then merges shared and per-cop defaults. The runner supplies a file's configuration before source construction when its selected format differs from RuboCop's default classification. This keeps nested configuration, explicit files, stdin, and autocorrection on the same dispatch path.
 
-## Documents and source preservation
+## Documents and Source Preservation
 
 `Document` retains the untouched input buffer and exposes character-based ranges. `MarkdownDocument` parses Markdown and provides its structure; `TextDocument` groups nonblank lines into paragraphs without interpreting headings, links, fences, HTML, or metadata. Text indentation may indicate preformatted content, so indented paragraphs can be reported but are not automatically reflowed.
 
@@ -20,13 +20,19 @@ Standalone Markdown and all plain text initialize Ruby parsing with empty input
 
 Each Markdown document shares positioned emphasis and strong ranges across style and spacing cops, including table-row source mapping. Both types are collected in one parse; style policies remain cop-local, and corrected sources receive fresh documents.
 
-## Preprocessor interoperability
+Source-oriented table scanning is also shared per document across table cops and structural blank-line protection. Corrected sources rebuild the table analysis rather than reusing stale cell positions.
+
+Eligible inline lines and their protected spans are shared per document, not across configurations or corrections. Link destination parsing is cached by original-source position, and rendered link labels by their exact source spelling; cached destinations always describe the untouched source, not the masked scanner buffer.
+
+## Preprocessor Interoperability
 
 An optional Markdown preprocessor can expose `processed_source.markdown_document` with an untouched `buffer` and `original_range` / `processed_range` mapping methods. The plugin analyzes that original buffer and translates offense and correction ranges at the RuboCop boundary, preserving the preprocessor's Ruby buffer so both kinds of corrections can coexist. This API is optional; standalone Markdown and text linting do not require a preprocessor.
 
 Plain text never consults the preprocessor API. A preprocessor without the original-buffer mapping methods is unsupported. Custom Markdown extensions remain lintable standalone when the preprocessor does not recognize them; Ruby extraction is then unavailable. The shared `Markdown:` section preserves keys owned by the preprocessor, while `IgnoreFrontMatter` belongs to this plugin.
 
-## Correction safety
+Parser warnings belong to `Markdown/KramdownSyntax` in this plugin. The former `Markdown/Syntax` name is not registered as obsolete because RuboCop-md 3.0.0 owns that name; rejecting or redirecting it would break valid preprocessor configuration.
+
+## Correction Safety
 
 Corrections are limited to rewrites whose source mapping and resulting document semantics are known. Markdown reflow preserves container prefixes, hard breaks, inline atomic syntax, and HTML break behavior; text preserves literal contents and paragraph boundaries. Unbreakable tokens and ambiguous structural rewrites can be reported without correction. Markdown structural checks do not reflow headings, tables, or code.
 
@@ -42,10 +48,12 @@ Shell-prompt removal preserves code-content ranges and container prefixes. Block
 
 `Markdown/ListContinuationIndentation` uses parsed list-item membership and each paragraph's original-source mapping to find continuation lines, excluding following root paragraphs and child list blocks. Its expected column comes from the parsed item's marker, so ordered marker widths and container prefixes are retained. It reports only: reindentation could change Markdown block ownership, so no correction is offered.
 
+`Markdown/ListItemPunctuation` uses parsed sibling membership and rendered inline text to check only terminal punctuation presence, not the punctuation character. Consistent mode uses the first item as its baseline; explicit always/never styles inspect every eligible item against the configured policy. It checks a list only when every item has exactly one paragraph and a source-mapped marker; code and multi-block items are ambiguous and skipped. Nested lists remain independent.
+
 Cop guides describe user-visible behavior and correction limits. Parsing, source mapping, and correction rationale belong here rather than in individual guides.
 
 ## Artwork
 
 The logo pairs the RuboCop helmet with a parchment scroll, keeping both silhouettes legible at the README's 160px display size. Its opaque white background preserves contrast on dark pages.
 
-`assets/rubocop-logo.svg` is copied unchanged from [the official website's SVG at a pinned commit](https://github.com/rubocop/rubocop.org/blob/e48d295d87264ea7dbfa0c6df7c7c4b56670979d/src/images/favicon.svg). The upstream MIT copyright and permission notice is preserved in [assets/RUBOCOP-LICENSE](assets/RUBOCOP-LICENSE); the newly drawn scroll uses this repository's [MIT license](LICENSE.txt). Editing and rendering instructions are in [CONTRIBUTING.md](CONTRIBUTING.md#artwork), and all artwork sources, rendered images, and the notice are packaged together.
+The `assets/rubocop-logo.svg` asset is copied unchanged from [the official website's SVG at a pinned commit](https://github.com/rubocop/rubocop.org/blob/e48d295d87264ea7dbfa0c6df7c7c4b56670979d/src/images/favicon.svg). The upstream MIT copyright and permission notice is preserved in [assets/RUBOCOP-LICENSE](assets/RUBOCOP-LICENSE); the newly drawn scroll uses this repository's [MIT license](LICENSE.txt). Editing and rendering instructions are in [CONTRIBUTING.md](CONTRIBUTING.md#artwork), and all artwork sources, rendered images, and the notice are packaged together.

data/README.md

@@ -1,13 +1,20 @@
 <img src="assets/logo.gif" alt="The RuboCop helmet logo alongside a parchment scroll rolling up and unfurling." width="160">
 
-# rubocop-prose
+# `rubocop-prose`
 
-[![Lint](https://github.com/dblock/rubocop-prose/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/dblock/rubocop-prose/actions/workflows/lint.yml) [![Tests](https://github.com/dblock/rubocop-prose/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/dblock/rubocop-prose/actions/workflows/test.yml)
+[![Gem Version](https://badge.fury.io/rb/rubocop-prose.svg)](https://rubygems.org/gems/rubocop-prose) [![Lint](https://github.com/dblock/rubocop-prose/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/dblock/rubocop-prose/actions/workflows/lint.yml) [![Tests](https://github.com/dblock/rubocop-prose/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/dblock/rubocop-prose/actions/workflows/test.yml) [![Coverage Status](https://coveralls.io/repos/github/dblock/rubocop-prose/badge.svg?branch=main)](https://coveralls.io/github/dblock/rubocop-prose?branch=main)
 
 Markdown and plain-text prose checks for RuboCop.
 
 Use [rubocop-md](https://github.com/rubocop/rubocop-md) to lint Ruby code inside Markdown.
 
+- Lint Markdown and plain text with native RuboCop configuration and file discovery.
+- Wrap or unwrap paragraphs while preserving Markdown syntax and hard breaks.
+- Check headings, lists, links, tables, code blocks, and whitespace.
+- Validate YAML front matter, require keys, and restrict allowed keys.
+- Check reference definitions, local heading fragments, and image alternative text.
+- Configure capitalization and proper names, with automatic corrections where supported.
+
 This project was inspired by [To Wrap or Not to Wrap in Markdown](https://code.dblock.org/2021/06/07/to-wrap-or-not-to-wrap-in-markdown.html) and borrows many Markdown checks from [markdownlint](https://github.com/DavidAnson/markdownlint).
 
 ## Installation
@@ -15,7 +22,7 @@ This project was inspired by [To Wrap or Not to Wrap in Markdown](https://code.d
 Add to your Gemfile, then run `bundle install`:
 
 ```ruby
-gem 'rubocop-prose', '~> 0.1', require: false
+gem 'rubocop-prose', '~> 0.2', require: false
 ```
 
 Add it to `.rubocop.yml` using RuboCop's plugin interface:
@@ -27,6 +34,8 @@ plugins:
 
 Ruby 3.2 or newer and RuboCop 1.72.1 or newer within 1.x are supported.
 
+See [UPGRADING](UPGRADING.md) for breaking changes when updating an existing installation.
+
 ## Usage
 
 Given `example.md`:
@@ -52,9 +61,16 @@ Fix it automatically with `bundle exec rubocop -a example.md`.
 
 ## Cops
 
-### Markdown
+### Prose
 
-Markdown checks ignore [front matter](docs/settings/front_matter.md) by default and do not treat code blocks as prose. Dedicated code-block cops check their structure; [Markdown/HardTabs](docs/cops/markdown/hard_tabs.md) and [Markdown/StructuralLineLength](docs/cops/markdown/structural_line_length.md) can also inspect code content. Inline formatting checks leave code spans, links, escaped syntax, and HTML untouched unless they specifically check those constructs.
+| Cop                                                                        | Default  | Purpose                                                            |
+| ---                                                                        | ---      | -------                                                            |
+| [Prose/MaxLength](docs/cops/prose/max_length.md)                           | Enabled  | Wrap or unwrap prose paragraphs in Markdown and plain text.        |
+| [Prose/MultipleBlankLines](docs/cops/prose/multiple_blank_lines.md)        | Enabled  | Limit blank lines in prose and quotes, but not code.               |
+| [Prose/SentenceCapitalization](docs/cops/prose/sentence_capitalization.md) | Disabled | Check paragraph openings without changing quoted or code literals. |
+| [Prose/TrailingNewline](docs/cops/prose/trailing_newline.md)               | Enabled  | Require exactly one final newline.                                 |
+
+### Markdown
 
 | Cop                                                                                         | Default  | Purpose                                                                             |
 | ---                                                                                         | ---      | -------                                                                             |
@@ -78,9 +94,12 @@ Markdown checks ignore [front matter](docs/settings/front_matter.md) by default
 | [Markdown/FenceLanguage](docs/cops/markdown/fence_language.md)                              | Enabled  | Require a language and optionally restrict fence languages.                         |
 | [Markdown/FenceStyle](docs/cops/markdown/fence_style.md)                                    | Enabled  | Use backtick, tilde, or consistently styled fences.                                 |
 | [Markdown/FirstHeading](docs/cops/markdown/first_heading.md)                                | Disabled | Begin documents with a heading or front-matter title.                               |
+| [Markdown/FrontMatterKeys](docs/cops/markdown/front_matter_keys.md)                         | Disabled | Restrict allowed and require mandatory top-level front matter keys.                 |
+| [Markdown/FrontMatterSyntax](docs/cops/markdown/front_matter_syntax.md)                     | Enabled  | Report YAML syntax errors in closed leading front matter.                           |
 | [Markdown/HardBreakStyle](docs/cops/markdown/hard_break_style.md)                           | Enabled  | Use backslashes or trailing spaces for paragraph hard breaks.                       |
-| [Markdown/HardTabs](docs/cops/markdown/hard_tabs.md)                                        | Enabled  | Disallow hard tabs with code-language exceptions.                                   |
+| [Markdown/HardTabs](docs/cops/markdown/hard_tabs.md)                                        | Enabled  | Report hard tabs with code-block and language exceptions.                           |
 | [Markdown/HeadingBlankLines](docs/cops/markdown/heading_blank_lines.md)                     | Enabled  | Surround headings with blank lines.                                                 |
+| [Markdown/HeadingCapitalization](docs/cops/markdown/heading_capitalization.md)              | Disabled | Enforce initial capitalization or title case in headings.                           |
 | [Markdown/HeadingIncrement](docs/cops/markdown/heading_increment.md)                        | Enabled  | Increase heading levels without skipping levels.                                    |
 | [Markdown/HeadingIndentation](docs/cops/markdown/heading_indentation.md)                    | Enabled  | Avoid leading indentation before headings.                                          |
 | [Markdown/HeadingPunctuation](docs/cops/markdown/heading_punctuation.md)                    | Disabled | Avoid configured trailing heading punctuation.                                      |
@@ -88,24 +107,26 @@ Markdown checks ignore [front matter](docs/settings/front_matter.md) by default
 | [Markdown/HeadingStyle](docs/cops/markdown/heading_style.md)                                | Disabled | Use a consistent heading syntax.                                                    |
 | [Markdown/ImageAltText](docs/cops/markdown/image_alt_text.md)                               | Enabled  | Require nonblank Markdown image alternative text.                                   |
 | [Markdown/ImagePathSeparators](docs/cops/markdown/image_path_separators.md)                 | Enabled  | Use forward slashes in local image destinations.                                    |
+| [Markdown/KramdownSyntax](docs/cops/markdown/kramdown_syntax.md)                            | Enabled  | Report Kramdown GFM parser diagnostics.                                             |
 | [Markdown/LinkFragment](docs/cops/markdown/link_fragment.md)                                | Disabled | Validate local fragments using configurable heading anchors.                        |
 | [Markdown/LinkStyle](docs/cops/markdown/link_style.md)                                      | Disabled | Configure permitted link and image styles independently.                            |
 | [Markdown/LinkTextSpacing](docs/cops/markdown/link_text_spacing.md)                         | Enabled  | Remove leading and trailing whitespace from link text.                              |
 | [Markdown/ListBlankLines](docs/cops/markdown/list_blank_lines.md)                           | Enabled  | Surround parsed lists with blank lines.                                             |
 | [Markdown/ListContinuationIndentation](docs/cops/markdown/list_continuation_indentation.md) | Enabled  | Indent list continuation text to its item's content column.                         |
 | [Markdown/ListIndentation](docs/cops/markdown/list_indentation.md)                          | Enabled  | Keep sibling list markers consistently indented.                                    |
+| [Markdown/ListItemCapitalization](docs/cops/markdown/list_item_capitalization.md)           | Disabled | Enforce consistent initials, initial capitals, or title case in list items.         |
+| [Markdown/ListItemPunctuation](docs/cops/markdown/list_item_punctuation.md)                 | Disabled | Require, forbid, or consistently use terminal punctuation in list items.            |
 | [Markdown/ListMarkerSpacing](docs/cops/markdown/list_marker_spacing.md)                     | Enabled  | Configure spaces after ordered and unordered list markers.                          |
 | [Markdown/OrderedListNumbering](docs/cops/markdown/ordered_list_numbering.md)               | Disabled | Use sequential numbers or repeated ones in ordered lists.                           |
 | [Markdown/OutsideSpacing](docs/cops/markdown/outside_spacing.md)                            | Enabled  | Report inline formatting directly adjacent to prose words.                          |
-| [Markdown/ProperNames](docs/cops/markdown/proper_names.md)                                  | Disabled | Use configured capitalization for proper names.                                     |
-| [Markdown/RawHtml](docs/cops/markdown/raw_html.md)                                          | Disabled | Disallow raw HTML except explicitly allowed elements.                               |
-| [Markdown/ReferenceDefinitions](docs/cops/markdown/reference_definitions.md)                | Enabled  | Report unused and duplicate reference definitions.                                  |
+| [Markdown/ProperNames](docs/cops/markdown/proper_names.md)                                  | Disabled | Use configured capitalization for proper names outside protected Markdown syntax.   |
+| [Markdown/RawHtml](docs/cops/markdown/raw_html.md)                                          | Disabled | Disallow raw HTML except allowed elements, with optional attribute allowlists.      |
+| [Markdown/ReferenceDefinitions](docs/cops/markdown/reference_definitions.md)                | Enabled  | Report duplicate and optionally unused reference definitions.                       |
 | [Markdown/ReversedLink](docs/cops/markdown/reversed_link.md)                                | Enabled  | Report reversed Markdown link delimiters.                                           |
 | [Markdown/ShellPrompts](docs/cops/markdown/shell_prompts.md)                                | Enabled  | Omit configured shell prompts in examples without output.                           |
 | [Markdown/SingleTopLevelHeading](docs/cops/markdown/single_top_level_heading.md)            | Disabled | Allow at most one top-level heading.                                                |
 | [Markdown/StrongStyle](docs/cops/markdown/strong_style.md)                                  | Enabled  | Use a configured or consistent strong delimiter.                                    |
 | [Markdown/StructuralLineLength](docs/cops/markdown/structural_line_length.md)               | Disabled | Report overlong heading, code-block, and table source lines without reflowing them. |
-| [Markdown/Syntax](docs/cops/markdown/syntax.md)                                             | Enabled  | Report native Markdown parser diagnostics.                                          |
 | [Markdown/TableBlankLines](docs/cops/markdown/table_blank_lines.md)                         | Enabled  | Surround Markdown tables with blank lines.                                          |
 | [Markdown/TableColumns](docs/cops/markdown/table_columns.md)                                | Enabled  | Match table body column counts to the header.                                       |
 | [Markdown/TablePipes](docs/cops/markdown/table_pipes.md)                                    | Enabled  | Use consistent leading and trailing table pipes.                                    |
@@ -117,9 +138,6 @@ Markdown checks ignore [front matter](docs/settings/front_matter.md) by default
 | [Markdown/UndefinedReference](docs/cops/markdown/undefined_reference.md)                    | Enabled  | Require definitions for link and image references.                                  |
 | [Markdown/UnorderedListIndentation](docs/cops/markdown/unordered_list_indentation.md)       | Enabled  | Use a configured indentation width for unordered lists.                             |
 | [Markdown/UnorderedListMarker](docs/cops/markdown/unordered_list_marker.md)                 | Enabled  | Use a configured or consistent unordered list marker.                               |
-| [Prose/MaxLength](docs/cops/prose/max_length.md)                                            | Enabled  | Wrap or unwrap prose paragraphs in Markdown and plain text.                         |
-| [Prose/MultipleBlankLines](docs/cops/prose/multiple_blank_lines.md)                         | Enabled  | Limit blank lines in prose and quotes, but not code.                                |
-| [Prose/TrailingNewline](docs/cops/prose/trailing_newline.md)                                | Enabled  | Require exactly one final newline.                                                  |
 
 #### Settings
 
@@ -130,12 +148,11 @@ Markdown checks ignore [front matter](docs/settings/front_matter.md) by default
 
 ### Text
 
-| Cop                                                                 | Default | Purpose                                                     |
-| ---                                                                 | ---     | -------                                                     |
-| [Prose/MaxLength](docs/cops/prose/max_length.md)                    | Enabled | Wrap or unwrap prose paragraphs in Markdown and plain text. |
-| [Prose/MultipleBlankLines](docs/cops/prose/multiple_blank_lines.md) | Enabled | Limit consecutive literal blank lines.                      |
-| [Prose/TrailingNewline](docs/cops/prose/trailing_newline.md)        | Enabled | Require exactly one final newline.                          |
-| [Text/TrailingWhitespace](docs/cops/text/trailing_whitespace.md)    | Enabled | Remove all trailing spaces and tabs from plain-text lines.  |
+| Cop                                                              | Default  | Purpose                                                         |
+| ---                                                              | ---      | -------                                                         |
+| [Text/HardTabs](docs/cops/text/hard_tabs.md)                     | Enabled  | Report tabs on every plain-text line without correction.        |
+| [Text/ProperNames](docs/cops/text/proper_names.md)               | Disabled | Use configured capitalization for proper names in literal text. |
+| [Text/TrailingWhitespace](docs/cops/text/trailing_whitespace.md) | Enabled  | Remove all trailing spaces and tabs from plain-text lines.      |
 
 #### Settings
 
@@ -143,7 +160,7 @@ Markdown checks ignore [front matter](docs/settings/front_matter.md) by default
 | ---                                    | ---                                                                     |
 | [Text/Include](docs/settings/files.md) | Select files parsed as literal text using native RuboCop file patterns. |
 
-## Project documentation
+## Project Documentation
 
 See [CONTRIBUTING](CONTRIBUTING.md) for development, testing, and artwork maintenance, [DESIGN](DESIGN.md) for architecture and design decisions, and [AGENTS](AGENTS.md) for contributor instructions for coding agents.
 

data/RELEASING.md

@@ -1,16 +1,16 @@
-# Releasing rubocop-prose
+# Releasing `rubocop-prose`
 
 Release only with explicit maintainer authorization. Release preparation happens on `main`; never force-push `main`.
 
 ## Prepare
 
-Update `main` with a fast-forward pull. Run `bundle exec rake` and confirm GitHub Actions checks pass, including the separate interoperability workflow. Verify the minimum supported RuboCop with `RUBOCOP_VERSION=1.72.1 bundle install` and `RUBOCOP_VERSION=1.72.1 bundle exec rake spec`; restore the normal dependency resolution afterward. Interoperability currently uses rubocop-md PR #57; update its workflow ref and README compatibility note when the original-source mapping API is released.
+Update `main` with a fast-forward pull. Run `bundle exec rake` and confirm GitHub Actions checks pass, including the separate interoperability workflow against the released `rubocop-md` tag `v3.0.0`. Verify the minimum supported RuboCop with `RUBOCOP_VERSION=1.72.1 bundle install` and `RUBOCOP_VERSION=1.72.1 bundle exec rake spec`; restore the normal dependency resolution afterward.
 
-Set the version in `lib/rubocop/prose/version.rb`, date its CHANGELOG heading as `YYYY/MM/DD`, remove the contribution placeholder from that release, and check README installation instructions. Commit and push preparation changes, wait for green CI, then build and inspect the package:
+Set the version in `lib/rubocop/prose/version.rb`, date its CHANGELOG heading as `YYYY/MM/DD`, remove the contribution placeholder from that release, update the target version in [UPGRADING](UPGRADING.md) and remove its `(Next)` marker, and check README installation instructions. Commit and push preparation changes, wait for green CI, then build and inspect the package:
 
 ```sh
 bundle exec rake build
-gem specification pkg/rubocop-prose-0.1.0.gem files
+gem specification pkg/rubocop-prose-0.2.0.gem files
 ```
 
 Confirm runtime code, configuration, cop guides, README, CHANGELOG, licenses, and artwork are present; exclude tests, temporary workspaces, and dependency caches. Preserve the vendored helmet license and provenance. Install the exact built gem into a temporary gem environment outside the checkout and exercise plugin loading, discovery, stdin, configuration, and repeated autocorrection for Markdown and text.
@@ -22,11 +22,11 @@ Publish the exact inspected package. Enter a fresh RubyGems MFA code when prompt
 For an assistant-driven release, ask the maintainer for a fresh MFA code only when ready to publish and pass it through `GEM_HOST_OTP_CODE`, not the `--otp` command-line argument. Prefer a hidden local prompt. If the maintainer explicitly chooses chat, explain that the code will be visible in conversation history. Never save the code in repository files or documentation. Alternatively, the maintainer can run `gem push` interactively.
 
 ```sh
-gem push pkg/rubocop-prose-0.1.0.gem
+gem push pkg/rubocop-prose-0.2.0.gem
 ```
 
-Verify that exact version on RubyGems before creating and pushing an annotated `v0.1.0` tag at the release commit. Create a GitHub release with matching changelog notes. Do not move an existing release tag.
+Verify that exact version on RubyGems before creating and pushing an annotated `v0.2.0` tag at the release commit. Create a GitHub release with matching changelog notes. Do not move an existing release tag.
 
-## Next development iteration
+## Next Development Iteration
 
-Bump the gem version, add a matching `(Next)` CHANGELOG section with `* Your contribution here.`, then commit and push to `main`.
+Bump the gem version, add a matching `(Next)` CHANGELOG section with `- Your contribution here.`, then commit and push to `main`.

data/UPGRADING.md

@@ -0,0 +1,16 @@
+# Upgrading
+
+Breaking changes are grouped by target release; follow the linked cop guides for configuration examples.
+
+## From 0.1.0 To 0.2.0
+
+- Rename this plugin's `Markdown/Syntax` configuration to [`Markdown/KramdownSyntax`](docs/cops/markdown/kramdown_syntax.md#migrating-from-010); `rubocop-md` now owns `Markdown/Syntax`.
+- Replace `EnforcedStyle` with `Style` in [`Markdown/CodeBlockStyle`](docs/cops/markdown/code_block_style.md#migrating-from-010).
+- Replace `EnforcedStyle` with `Style` in [`Markdown/FenceStyle`](docs/cops/markdown/fence_style.md#migrating-from-010).
+- Replace `EnforcedStyle` with `Style` in [`Markdown/HeadingStyle`](docs/cops/markdown/heading_style.md#migrating-from-010).
+- Replace `EnforcedStyle` with `Style` in [`Markdown/OrderedListNumbering`](docs/cops/markdown/ordered_list_numbering.md#migrating-from-010).
+- Replace `EnforcedStyle` with `Style` in [`Markdown/UnorderedListMarker`](docs/cops/markdown/unordered_list_marker.md#migrating-from-010).
+- Replace `OrderedSingle`, `OrderedMulti`, `UnorderedSingle`, and `UnorderedMulti` with shared `Style` and `MinSpaces` in [`Markdown/ListMarkerSpacing`](docs/cops/markdown/list_marker_spacing.md#migrating-from-010).
+- Replace shared `Max` and enable/value pairs with integer widths or `false` for `Headings`, `CodeBlocks`, and `Tables` in [`Markdown/StructuralLineLength`](docs/cops/markdown/structural_line_length.md#migrating-from-010).
+- Replace `CheckDuplicates` and `AllowIdenticalDuplicates` with `Duplicates`, and rename `CheckUnused` to `Unused` in [`Markdown/ReferenceDefinitions`](docs/cops/markdown/reference_definitions.md#migrating-from-010).
+- Replace `FrontMatterTitle: true` and `TitleKey` with `FrontMatterTitle: <metadata key>` (or `false`) in [`Markdown/FirstHeading`](docs/cops/markdown/first_heading.md#migrating-from-010).

data/assets/README.md

@@ -1,3 +1,3 @@
-# Logo artwork
+# Logo Artwork
 
 See [DESIGN.md](../DESIGN.md#artwork) for composition and source attribution, [CONTRIBUTING.md](../CONTRIBUTING.md#artwork) for editing and rendering instructions, and [RUBOCOP-LICENSE](RUBOCOP-LICENSE) for the upstream copyright and permission notice.

data/config/cops/markdown/code_block_style.yml

@@ -1,7 +1,7 @@
 Markdown/CodeBlockStyle:
   Description: Use fenced, indented, or consistently styled code blocks.
   Enabled: false
-  EnforcedStyle: consistent
+  Style: consistent
   SupportedStyles:
     - consistent
     - fenced

data/config/cops/markdown/emphasis_style.yml

@@ -2,3 +2,7 @@ Markdown/EmphasisStyle:
   Description: 'Use a configured or consistent emphasis delimiter.'
   Enabled: true
   Style: consistent
+  SupportedStyles:
+    - consistent
+    - asterisk
+    - underscore

data/config/cops/markdown/fence_style.yml

@@ -1,7 +1,7 @@
 Markdown/FenceStyle:
   Description: Use backtick, tilde, or consistently styled fences.
   Enabled: true
-  EnforcedStyle: consistent
+  Style: consistent
   SupportedStyles:
     - consistent
     - backtick

data/config/cops/markdown/first_heading.yml

@@ -2,5 +2,4 @@ Markdown/FirstHeading:
   Description: 'Begin documents with a heading or front-matter title.'
   Enabled: false
   Level: 1
-  FrontMatterTitle: true
-  TitleKey: title
+  FrontMatterTitle: title

data/config/cops/markdown/front_matter_keys.yml

@@ -0,0 +1,5 @@
+Markdown/FrontMatterKeys:
+  Description: Restrict allowed and require mandatory top-level YAML front matter keys.
+  Enabled: false
+  AllowedKeys:
+  RequiredKeys: []

data/config/cops/markdown/front_matter_syntax.yml

@@ -0,0 +1,3 @@
+Markdown/FrontMatterSyntax:
+  Description: 'Report invalid YAML syntax in closed leading front matter.'
+  Enabled: true

data/config/cops/markdown/hard_break_style.yml

@@ -2,3 +2,6 @@ Markdown/HardBreakStyle:
   Description: 'Use a configured Markdown hard-break syntax.'
   Enabled: true
   Style: backslash
+  SupportedStyles:
+    - backslash
+    - spaces

data/config/cops/markdown/hard_tabs.yml

@@ -1,5 +1,5 @@
 Markdown/HardTabs:
-  Description: 'Disallow hard tabs with code-language exceptions.'
+  Description: 'Report hard tabs in Markdown without correcting them.'
   Enabled: true
   CodeBlocks: false
   AllowedCodeLanguages: []

data/config/cops/markdown/heading_capitalization.yml

@@ -0,0 +1,31 @@
+Markdown/HeadingCapitalization:
+  Description: 'Enforce initial capitalization or title case in headings.'
+  Enabled: false
+  SafeAutoCorrect: false
+  Style: title_case
+  PreserveMixedCase: true
+  IgnoredWords: []
+  MinorWords:
+    - a
+    - an
+    - and
+    - as
+    - at
+    - but
+    - by
+    - for
+    - from
+    - in
+    - nor
+    - of
+    - 'on'
+    - or
+    - per
+    - the
+    - to
+    - via
+    - vs
+    - with
+  SupportedStyles:
+    - initial_capital
+    - title_case

data/config/cops/markdown/heading_style.yml

@@ -1,7 +1,7 @@
 Markdown/HeadingStyle:
   Description: 'Use a consistent heading syntax.'
   Enabled: false
-  EnforcedStyle: consistent
+  Style: consistent
   SupportedStyles:
     - consistent
     - atx

data/config/cops/markdown/{syntax.yml → kramdown_syntax.yml}

@@ -1,3 +1,3 @@
-Markdown/Syntax:
+Markdown/KramdownSyntax:
   Description: 'Report native Markdown parser diagnostics.'
   Enabled: true

data/config/cops/markdown/list_item_capitalization.yml

@@ -0,0 +1,32 @@
+Markdown/ListItemCapitalization:
+  Description: Enforce consistent initials, initial capitals, or title case in list items.
+  Enabled: false
+  SafeAutoCorrect: false
+  Style: consistent
+  SupportedStyles:
+    - consistent
+    - initial_capital
+    - title_case
+  PreserveMixedCase: true
+  IgnoredWords: []
+  MinorWords:
+    - a
+    - an
+    - and
+    - as
+    - at
+    - but
+    - by
+    - for
+    - from
+    - in
+    - nor
+    - of
+    - 'on'
+    - or
+    - per
+    - the
+    - to
+    - via
+    - vs
+    - with

data/config/cops/markdown/list_item_punctuation.yml

@@ -0,0 +1,13 @@
+Markdown/ListItemPunctuation:
+  Description: Require, forbid, or consistently use terminal punctuation in list items.
+  Enabled: false
+  Style: consistent
+  AllowedPunctuation:
+    - "."
+    - "!"
+    - "?"
+    - "…"
+  SupportedStyles:
+    - consistent
+    - always
+    - never

data/config/cops/markdown/list_marker_spacing.yml

@@ -1,7 +1,8 @@
 Markdown/ListMarkerSpacing:
-  Description: Configure spaces after ordered and unordered list markers.
+  Description: Enforce fixed or aligned spacing after list markers.
   Enabled: true
-  UnorderedSingle: 1
-  OrderedSingle: 1
-  UnorderedMulti: 1
-  OrderedMulti: 1
+  Style: fixed
+  SupportedStyles:
+    - fixed
+    - aligned
+  MinSpaces: 1

data/config/cops/markdown/ordered_list_numbering.yml

@@ -1,7 +1,7 @@
 Markdown/OrderedListNumbering:
   Description: Use sequential numbers or repeated ones in ordered lists.
   Enabled: false
-  EnforcedStyle: sequential
+  Style: sequential
   SupportedStyles:
     - sequential
     - ones