rubocop-prose 0.1.0 → 0.2.0

data/config/cops/markdown/reference_definitions.yml

@@ -1,8 +1,7 @@
 Markdown/ReferenceDefinitions:
   Description: 'Report unused and duplicate reference definitions.'
   Enabled: true
-  CheckUnused: false
-  CheckDuplicates: true
-  AllowIdenticalDuplicates: false
+  Duplicates: forbid
+  Unused: false
   IgnoredDefinitions:
     - '//'

data/config/cops/markdown/strong_style.yml

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

data/config/cops/markdown/structural_line_length.yml

@@ -1,9 +1,6 @@
 Markdown/StructuralLineLength:
   Description: Report overlong heading, code-block, and table source lines without reflowing them.
   Enabled: false
-  Max: 80
-  Headings: true
-  HeadingMax:
+  Headings: 80
   CodeBlocks: false
-  CodeBlockMax:
   Tables: false

data/config/cops/markdown/table_pipes.yml

@@ -2,3 +2,9 @@ Markdown/TablePipes:
   Description: 'Use consistent leading and trailing table pipes.'
   Enabled: true
   Style: consistent
+  SupportedStyles:
+    - consistent
+    - leading_and_trailing
+    - leading_only
+    - trailing_only
+    - no_leading_or_trailing

data/config/cops/markdown/table_spacing.yml

@@ -2,3 +2,7 @@ Markdown/TableSpacing:
   Description: 'Use configured spacing around table cell content.'
   Enabled: true
   Style: aligned
+  SupportedStyles:
+    - aligned
+    - compact
+    - tight

data/config/cops/markdown/trailing_whitespace.yml

@@ -2,4 +2,5 @@ Markdown/TrailingWhitespace:
   Description: 'Remove trailing whitespace while retaining Markdown hard breaks.'
   Enabled: true
   HardBreakSpaces: 2
+  AllowEmptyBlockquoteSpace: false
   CodeBlocks: false

data/config/cops/markdown/unordered_list_marker.yml

@@ -1,7 +1,7 @@
 Markdown/UnorderedListMarker:
   Description: Use a configured or consistent unordered list marker.
   Enabled: true
-  EnforcedStyle: consistent
+  Style: consistent
   SupportedStyles:
     - consistent
     - asterisk

data/config/cops/prose/sentence_capitalization.yml

@@ -0,0 +1,9 @@
+Prose/SentenceCapitalization:
+  Description: Check capitalization of paragraph openings without rewriting literal terms.
+  Enabled: false
+  SafeAutoCorrect: false
+  Style: initial_capital
+  PreserveMixedCase: true
+  IgnoredWords: []
+  SupportedStyles:
+    - initial_capital

data/config/cops/text/hard_tabs.yml

@@ -0,0 +1,3 @@
+Text/HardTabs:
+  Description: 'Report hard tabs on every plain-text line without correcting them.'
+  Enabled: true

data/config/cops/text/proper_names.yml

@@ -0,0 +1,4 @@
+Text/ProperNames:
+  Description: 'Use configured capitalization for proper names in literal text.'
+  Enabled: false
+  Names: []

data/config/obsoletion.yml

@@ -0,0 +1,45 @@
+changed_parameters:
+  - cops: Markdown/StructuralLineLength
+    parameters:
+      - Max
+      - HeadingMax
+      - CodeBlockMax
+    reason: >-
+      Replace the shared limit and enable/value pairs with a positive integer width (or false) for each element:
+      Headings, CodeBlocks, and Tables. For example, use Headings: 120, CodeBlocks: false, and Tables: false.
+  - cops: Markdown/ReferenceDefinitions
+    parameters:
+      - CheckDuplicates
+      - AllowIdenticalDuplicates
+    reason: >-
+      Replace CheckDuplicates and AllowIdenticalDuplicates with Duplicates.
+      CheckDuplicates: false maps to Duplicates: allow, regardless of AllowIdenticalDuplicates.
+      CheckDuplicates: true (or omitted) with AllowIdenticalDuplicates: true maps to Duplicates: allow_identical.
+      Otherwise, the default maps to Duplicates: forbid.
+      Remove both legacy keys; combinations are not translated automatically.
+  - cops: Markdown/ReferenceDefinitions
+    parameters: CheckUnused
+    reason: 'Replace CheckUnused with Unused, preserving its boolean value (default: false).'
+  - cops:
+      - Markdown/CodeBlockStyle
+      - Markdown/FenceStyle
+      - Markdown/HeadingStyle
+      - Markdown/OrderedListNumbering
+      - Markdown/UnorderedListMarker
+    parameters: EnforcedStyle
+    alternative: Style
+  - cops: Markdown/ListMarkerSpacing
+    parameters:
+      - OrderedSingle
+      - OrderedMulti
+      - UnorderedSingle
+      - UnorderedMulti
+    reason: >-
+      Use Style (fixed or aligned) and MinSpaces instead.
+      These settings now apply to all list items, regardless of marker type or multiline content.
+      Different legacy spacing values cannot be preserved by a single policy; choose the desired shared spacing.
+  - cops: Markdown/FirstHeading
+    parameters:
+      - TitleKey
+    reason: >-
+      Set FrontMatterTitle to the desired metadata key, or false to disable the front-matter title exemption.

data/docs/cops/markdown/blockquote_spacing.md

@@ -4,6 +4,8 @@ Requires one space after each nonempty blockquote marker, including nested marke
 
 Empty quote lines and indentation inside quoted lists and code are preserved. Missing separators are autocorrected only when reparsing confirms the Markdown structure is unchanged; otherwise, the offense is report-only.
 
+[Markdown/TrailingWhitespace](trailing_whitespace.md) independently trims trailing whitespace on empty quote lines; its opt-in `AllowEmptyBlockquoteSpace` permits one trailing space.
+
 ## Configuration
 
 ```yaml

data/docs/cops/markdown/code_block_style.md

@@ -9,7 +9,7 @@ Autocorrection is limited to standalone root-level blocks with blank boundaries.
 ```yaml
 Markdown/CodeBlockStyle:
   Enabled: false
-  EnforcedStyle: consistent # consistent, fenced or indented.
+  Style: consistent # consistent, fenced or indented.
 ```
 
 ## Example
@@ -19,7 +19,7 @@ For this configuration:
 ```yaml
 Markdown/CodeBlockStyle:
   Enabled: true
-  EnforcedStyle: fenced
+  Style: fenced
 ```
 
 ### Bad
@@ -35,3 +35,12 @@ Markdown/CodeBlockStyle:
 puts 'hello'
 ```
 ````
+
+## Migrating From 0.1.0
+
+Replace `EnforcedStyle` with `Style`:
+
+```yaml
+Markdown/CodeBlockStyle:
+  Style: fenced
+```

data/docs/cops/markdown/duplicate_headings.md

@@ -12,6 +12,57 @@ Markdown/DuplicateHeadings:
   Scope: siblings # Or document to compare headings across the entire document.
 ```
 
+## Level-Specific Scopes
+
+`Scope` accepts `document`, `siblings`, or `false` (disable duplicate checks). It also accepts a mapping with a required `Default` and level selectors. Unlisted levels inherit `Default`. Every value accepts the same three choices.
+
+Selectors can be integer levels from 1 through 6, quoted inclusive ranges such as `"4-6"`, or quoted strict comparisons such as `">4"` (levels five and six) and `"<3"` (levels one and two). Overlapping selectors, reversed or empty ranges, missing defaults, and invalid scopes are configuration errors; there is no selector precedence.
+
+For this configuration:
+
+```yaml
+Markdown/DuplicateHeadings:
+  Scope:
+    Default: document
+    4: siblings
+    5: siblings
+    6: siblings
+```
+
+Levels one through three require document-wide uniqueness. Deeper headings require uniqueness only among siblings:
+
+```markdown
+# Guide
+
+## Services
+
+### Service Overview
+
+#### Details
+
+## Clients
+
+### Client Overview
+
+#### Details
+```
+
+Both `Details` headings are allowed because they have different parents. Replacing `Client Overview` with `Service Overview` is reported because level three uses document scope. Repeating `Details` under the same parent is still reported.
+
+Each heading's effective scope determines which earlier headings it is compared against, including headings at other levels or with different configured scopes. This preserves existing cross-level comparison semantics: document scope compares against all earlier headings, while sibling scope compares against earlier headings sharing the same parent, including skipped levels.
+
+To disable checks for deeper headings:
+
+```yaml
+Markdown/DuplicateHeadings:
+  Scope:
+    Default: document
+    4: siblings
+    ">4": false
+```
+
+Alternatively, `"4-6": false` disables levels four through six. Disabled headings still establish parent ancestry and remain available for comparison when a later heading's effective scope checks them; they simply do not receive duplicate diagnostics themselves.
+
 ## Example
 
 ### Bad

data/docs/cops/markdown/emphasis_style.md

@@ -9,7 +9,11 @@ Autocorrection preserves content. Intraword asterisks are not changed to undersc
 ```yaml
 Markdown/EmphasisStyle:
   Enabled: true
-  Style: consistent # consistent, asterisk or underscore.
+  Style: consistent
+  SupportedStyles:
+    - consistent
+    - asterisk
+    - underscore
 ```
 
 ## Example

data/docs/cops/markdown/fence_style.md

@@ -9,7 +9,7 @@ Autocorrection preserves contents, language metadata, and nesting. Conversion to
 ```yaml
 Markdown/FenceStyle:
   Enabled: true
-  EnforcedStyle: consistent # consistent, backtick or tilde.
+  Style: consistent # consistent, backtick or tilde.
 ```
 
 ## Example
@@ -18,7 +18,7 @@ For this configuration:
 
 ```yaml
 Markdown/FenceStyle:
-  EnforcedStyle: backtick
+  Style: backtick
 ```
 
 ### Bad
@@ -36,3 +36,12 @@ puts 1
 puts 1
 ```
 ````
+
+## Migrating From 0.1.0
+
+Replace `EnforcedStyle` with `Style`:
+
+```yaml
+Markdown/FenceStyle:
+  Style: backtick
+```

data/docs/cops/markdown/first_heading.md

@@ -1,6 +1,6 @@
 # Markdown/FirstHeading
 
-Requires the first content line to be a heading at the configured level, unless a configured front-matter title qualifies. Empty documents are accepted.
+Requires the first content line to be a heading at the configured level, unless the configured front-matter metadata key contains a nonempty string. The default key is `title`; set `FrontMatterTitle: false` to require a heading even when front matter contains a title. Empty documents are accepted.
 
 Front-matter titles must be strings; YAML aliases are not accepted. Report-only: adding or moving a heading changes structure.
 
@@ -10,8 +10,7 @@ Front-matter titles must be strings; YAML aliases are not accepted. Report-only:
 Markdown/FirstHeading:
   Enabled: false
   Level: 1
-  FrontMatterTitle: true # Accept a nonempty front-matter title instead of a heading.
-  TitleKey: title # Exact top-level YAML key, not a regular expression.
+  FrontMatterTitle: title # Exact top-level YAML key, or false to disable the exemption.
 ```
 
 ## Example
@@ -29,3 +28,30 @@ An introduction to the project.
 
 An introduction to the project.
 ```
+
+### Good Front Matter Title
+
+```markdown
+---
+title: Introduction
+---
+
+An introduction to the project.
+```
+
+## Migrating From 0.1.0
+
+In 0.1.0, `FrontMatterTitle: true` enabled the exemption and `TitleKey` selected the metadata key. Replace that pair with one setting: a nonempty key string, or `false` to disable the exemption. For example, migrate a custom `name` key as follows:
+
+```yaml
+# Before
+Markdown/FirstHeading:
+  FrontMatterTitle: true
+  TitleKey: name
+
+# After
+Markdown/FirstHeading:
+  FrontMatterTitle: name
+```
+
+`TitleKey` is obsolete and causes a configuration error with migration guidance. Use `FrontMatterTitle: false` when the front matter should not satisfy this cop.

data/docs/cops/markdown/front_matter_keys.md

@@ -0,0 +1,57 @@
+# Markdown/FrontMatterKeys
+
+Checks allowed and required top-level keys in a closed leading YAML front-matter block. Key names are exact and case-sensitive. Nested keys and values are not checked. Required keys must be present, but may have empty values.
+
+`AllowedKeys: null` permits any key; `[]` permits none. `RequiredKeys` lists keys that must appear and must be included in `AllowedKeys` when that allowlist is configured. A document without front matter is skipped; an empty front-matter block is checked for missing keys.
+
+Checks run even when `Markdown/IgnoreFrontMatter` is true. Malformed YAML is skipped so `Markdown/FrontMatterSyntax` can report syntax errors separately. Non-mapping YAML and complex or alias keys are reported. YAML merge keys (`<<`) are treated as literal keys, not expanded; quoted scalar keys are compared by their decoded text. Parsing uses the YAML syntax tree and never instantiates tagged Ruby objects.
+
+Report-only: removing unknown metadata or inventing required values could lose data or change behavior.
+
+## Configuration
+
+```yaml
+Markdown/FrontMatterKeys:
+  Enabled: false
+  AllowedKeys: null
+  RequiredKeys: []
+```
+
+## Example
+
+For this configuration:
+
+```yaml
+Markdown/FrontMatterKeys:
+  Enabled: true
+  AllowedKeys:
+    - title
+    - date
+    - tags
+  RequiredKeys:
+    - title
+```
+
+### Bad
+
+```markdown
+---
+titel: Getting Started
+date: 2026-11-05
+---
+
+# Getting Started
+```
+
+### Good
+
+```markdown
+---
+title: Getting Started
+date: 2026-11-05
+tags:
+  - ruby
+---
+
+# Getting Started
+```

data/docs/cops/markdown/front_matter_syntax.md

@@ -0,0 +1,32 @@
+# Markdown/FrontMatterSyntax
+
+Reports YAML syntax errors in closed leading Markdown front matter. The cop is enabled by default and report-only. It parses YAML syntax without constructing Ruby objects or validating metadata against a schema; valid scalar values such as dates and custom-tagged nodes are accepted.
+
+The cop checks only a closed leading header and reports the YAML parser's line and column in the original Markdown source. It works independently of `Markdown: IgnoreFrontMatter`, which controls how other Markdown cops handle metadata.
+
+## Configuration
+
+```yaml
+Markdown/FrontMatterSyntax:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+---
+title: [Unclosed list
+---
+```
+
+### Good
+
+```markdown
+---
+title: A valid title
+date: 2026-11-04
+tags: [ruby, markdown]
+---
+```

data/docs/cops/markdown/hard_break_style.md

@@ -4,24 +4,29 @@ Requires Markdown paragraph hard breaks to use the configured backslash or trail
 
 On files whose line endings cannot be preserved by RuboCop's source buffer, this cop reports style violations without autocorrecting them.
 
+Trailing whitespace cleanup honors this style.
+
 ## Configuration
 
 ```yaml
 Markdown/HardBreakStyle:
   Enabled: true
-  Style: backslash # backslash or spaces.
+  Style: backslash
+  SupportedStyles:
+    - backslash
+    - spaces
 ```
 
 ## Example
 
-### Bad: trailing spaces
+### Bad: Trailing Spaces
 
 ```markdown
 First line.  
 Second line.
 ```
 
-### Good: backslash
+### Good: Backslash
 
 ```markdown
 First line.\
@@ -35,14 +40,14 @@ Markdown/HardBreakStyle:
   Style: spaces
 ```
 
-### Bad: backslash
+### Bad: Backslash
 
 ```markdown
 First line.\
 Second line.
 ```
 
-### Good: trailing spaces
+### Good: Trailing Spaces
 
 ```markdown
 First line.  

data/docs/cops/markdown/hard_tabs.md

@@ -1,15 +1,15 @@
 # Markdown/HardTabs
 
-Reports hard tabs, with configurable code-language exceptions.
+Reports hard tabs in Markdown. Front matter and code-block contents are ignored by default. Enable `CodeBlocks` to inspect code contents; `AllowedCodeLanguages` exempts configured fenced languages.
 
-Report-only: replacing tabs can change embedded code or Makefiles.
+Report-only: tabs may be intentional for alignment, Makefiles, or embedded code. Use [Text/HardTabs](../text/hard_tabs.md) for literal plain-text files.
 
 ## Configuration
 
 ```yaml
 Markdown/HardTabs:
   Enabled: true
-  CodeBlocks: false # Preserve tabs in code examples; set true to inspect code.
+  CodeBlocks: false # Set true to inspect code-block contents.
   AllowedCodeLanguages: [] # Case-insensitive fenced languages to exempt, such as make.
 ```
 

data/docs/cops/markdown/heading_capitalization.md

@@ -0,0 +1,176 @@
+# Markdown/HeadingCapitalization
+
+Checks ATX and Setext headings, ignoring emphasis delimiters, link syntax, and leading punctuation or numbers. `Style: title_case` (the default) checks each word, keeping internal minor words lowercase. `initial_capital` checks only the first prose letter; remaining words retain their capitalization. Neither style enforces strict sentence case.
+
+Lowercase openings inside inline code or quoted terms are reported, including ``## `excalc` usage`` and `## "excalc" usage`; neither their literal contents nor later words are changed. Opaque leading content such as HTML or images is conservatively skipped. `PreserveMixedCase: true` (the default) preserves mixed-case words such as `eBay`, `iOS`, and `macOS` where an initial capital is required, in either style. Set it to `false` to require uppercase initials even for those words. `IgnoredWords` still takes precedence.
+
+Use native RuboCop suppression directives for intentional lowercase headings. [Markdown/ProperNames](proper_names.md) independently enforces configured canonical spellings; its configuration does not exempt headings from this cop.
+
+`IgnoredWords` skips exact, case-sensitive whole words in either style without exempting the rest of the heading. Mixed-case brands such as `macOS` already pass; use this option for additional spellings such as `npm`.
+
+Supports unsafe autocorrection (`rubocop -A`): capitalization may express proper-name intent, and changing a heading can change its generated link anchor. Corrections preserve prefixes, closing markers, and Setext underlines. They are offered only when the rendered heading text maps to one contiguous, unique source span outside protected inline syntax. Split formatting, links, encoded entities, multiline headings, and other ambiguous mappings remain report-only.
+
+## Configuration
+
+```yaml
+Markdown/HeadingCapitalization:
+  Enabled: 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
+```
+
+## Initial Capital
+
+For this configuration:
+
+```yaml
+Markdown/HeadingCapitalization:
+  Enabled: true
+  Style: initial_capital
+```
+
+### Bad
+
+```markdown
+## installing the package
+
+*getting* started
+-----------------
+```
+
+### Good
+
+```markdown
+## Installing the package
+
+*Getting* started
+-----------------
+
+## `Excalc` usage
+
+## eBay integration
+```
+
+## Title Case
+
+For this configuration:
+
+```yaml
+Markdown/HeadingCapitalization:
+  Enabled: true
+  Style: title_case
+```
+
+### Bad
+
+```markdown
+## Getting started with the API
+
+## Getting Started With The API
+
+## the API and
+```
+
+### Good
+
+```markdown
+## Getting Started with the API
+
+## The API And
+
+## Getting Started with macOS and the API
+```
+
+The minor words are `a`, `an`, `and`, `as`, `at`, `but`, `by`, `for`, `from`, `in`, `nor`, `of`, `on`, `or`, `per`, `the`, `to`, `via`, `vs`, and `with`. They must be lowercase except as the first or last word. Other words must start uppercase, with mixed-case words also accepted when `PreserveMixedCase` is enabled. Acronyms with uppercase initials and uncased scripts are accepted regardless of that option. Apostrophes stay within words; hyphens separate words, as in `Don't Re-enter the API`.
+
+This is a word-based policy, not grammatical analysis or a publishing style manual. Title case skips the entire heading when it contains inline code, HTML, images, or other opaque content rather than guessing word boundaries, except that a lowercase literal opening is reported without correction.
+
+### Customize Minor Words
+
+`MinorWords` replaces the default list and matches case-insensitively. It affects only `title_case`; first and last words still require capitals. Set it to `[]` to capitalize every word. `IgnoredWords` takes precedence over minor-word rules.
+
+For this configuration:
+
+```yaml
+Markdown/HeadingCapitalization:
+  Enabled: true
+  Style: title_case
+  MinorWords:
+    - and
+    - the
+```
+
+#### Bad
+
+```markdown
+## Getting Started with the API
+```
+
+#### Good
+
+```markdown
+## Getting Started With the API
+```
+
+## Ignore Specific Words
+
+For example, with `PreserveMixedCase: false`, `## Using macOS` is reported in title-case style unless `macOS` is included in `IgnoredWords`.
+
+For this configuration:
+
+```yaml
+Markdown/HeadingCapitalization:
+  Enabled: true
+  Style: title_case
+  IgnoredWords:
+    - macOS
+    - npm
+```
+
+### Bad
+
+```markdown
+## Getting started with macOS
+
+## Using npmlike on macOS
+```
+
+### Good
+
+```markdown
+## Getting Started with macOS
+
+## Using npm on macOS
+```
+
+Entries are individual words, not phrases or patterns. Ignoring `npm` does not ignore `npmlike` or exempt other lowercase words.
+
+### Suppress an Intentional Lowercase Heading
+
+```markdown
+<!-- # rubocop:disable Markdown/HeadingCapitalization -->
+## npm usage
+<!-- # rubocop:enable Markdown/HeadingCapitalization -->
+```