rubocop-prose 0.1.0 → 0.2.0

data/docs/cops/markdown/heading_style.md

@@ -9,7 +9,7 @@ Report-only: changing syntax can alter heading levels or surrounding structure.
 ```yaml
 Markdown/HeadingStyle:
   Enabled: false
-  EnforcedStyle: consistent # consistent, atx, atx_closed or setext.
+  Style: consistent # consistent, atx, atx_closed or setext.
 ```
 
 ## Example
@@ -19,7 +19,7 @@ For this configuration:
 ```yaml
 Markdown/HeadingStyle:
   Enabled: true
-  EnforcedStyle: atx
+  Style: atx
 ```
 
 ### Bad
@@ -34,3 +34,12 @@ Title
 ```markdown
 # Title
 ```
+
+## Migrating From 0.1.0
+
+Replace `EnforcedStyle` with `Style`:
+
+```yaml
+Markdown/HeadingStyle:
+  Style: atx
+```

data/docs/cops/markdown/{syntax.md → kramdown_syntax.md}

@@ -1,4 +1,4 @@
-# Markdown/Syntax
+# Markdown/KramdownSyntax
 
 Reports Kramdown GFM parsing warnings through RuboCop. Report-only.
 
@@ -7,7 +7,7 @@ Reference warnings are handled by [Markdown/UndefinedReference](undefined_refere
 ## Configuration
 
 ```yaml
-Markdown/Syntax:
+Markdown/KramdownSyntax:
   Enabled: true
 ```
 
@@ -26,3 +26,7 @@ Markdown/Syntax:
 
 [docs]: /guide
 ```
+
+## Migrating From 0.1.0
+
+Rename this plugin's `Markdown/Syntax` configuration to `Markdown/KramdownSyntax`. When using RuboCop-md 3.0.0 or newer, `Markdown/Syntax` configures its separate cop; leave that disabled to avoid duplicate parser warnings.

data/docs/cops/markdown/list_item_capitalization.md

@@ -0,0 +1,115 @@
+# Markdown/ListItemCapitalization
+
+Checks capitalization in ordered and unordered list items. `Style` supports `consistent` (default), `initial_capital`, and `title_case`. The word settings follow [Markdown/HeadingCapitalization](heading_capitalization.md).
+
+In `consistent` mode, the first eligible item establishes uppercase or lowercase initials; nested and separate lists establish their own style. `initial_capital` requires uppercase initials regardless of sibling style. Both inspect only the initial word, including emphasis, link labels, quotes, inline code, and optional task checkboxes. Code and quoted openings are treated as literal text and are never autocorrected. Images, HTML, entities, numbers, punctuation, uncased letters, paths, URLs, and ambiguous identifiers are skipped. The cop does not search later in an item for prose.
+
+The `title_case` style checks the first paragraph of each item, capitalizing major words and keeping internal `MinorWords` lowercase. First and last words require capitals. It skips paragraphs containing opaque inline content such as code, images, or HTML, except that lowercase literal openings are reported without correction.
+
+`IgnoredWords` exempts exact, case-sensitive words; in initial styles, exempt items neither establish nor match a baseline. `PreserveMixedCase: true` preserves brands and acronyms such as `macOS` and `API` without establishing a consistency baseline. Set it to `false` to check their initials normally; this does not lowercase internal capitals. `MinorWords` replaces the defaults, matches case-insensitively, and affects only title case. An empty list requires every word to be capitalized. Ignored words take precedence over other checks.
+
+Supports unsafe autocorrection with `rubocop -A`, since casing can change proper names or identifiers. Initial-style corrections replace only the first letter. Title-case corrections require a unique, contiguous source mapping outside protected inline syntax; split formatting, links, encoded entities, and multiline text may remain report-only. Container markers, task checkboxes, nested lists, and later paragraphs are preserved.
+
+## Configuration
+
+```yaml
+Markdown/ListItemCapitalization:
+  Enabled: false
+  Style: consistent
+  PreserveMixedCase: true
+  IgnoredWords: []
+  MinorWords:
+    - a
+    - an
+    - and
+    - as
+    - at
+    - but
+    - by
+    - for
+    - from
+    - in
+    - nor
+    - of
+    - 'on'
+    - or
+    - per
+    - the
+    - to
+    - via
+    - vs
+    - with
+```
+
+## Consistent Initials
+
+### Bad
+
+```markdown
+- Build the package
+- run the tests.
+```
+
+### Good
+
+```markdown
+- Build the package
+- Run the tests.
+  - check the output
+  - review the logs
+```
+
+## Initial Capitals
+
+For this configuration:
+
+```yaml
+Markdown/ListItemCapitalization:
+  Enabled: true
+  Style: initial_capital
+```
+
+### Bad
+
+```markdown
+- build the package
+- run the tests
+```
+
+### Good
+
+```markdown
+- Build the package
+- Run the tests
+```
+
+## Title Case and Word Settings
+
+For this configuration:
+
+```yaml
+Markdown/ListItemCapitalization:
+  Enabled: true
+  Style: title_case
+  PreserveMixedCase: false
+  IgnoredWords:
+    - macOS
+    - npm
+  MinorWords:
+    - the
+    - with
+```
+
+### Bad
+
+```markdown
+- getting started with macOS
+- Using The API with npm
+```
+
+### Good
+
+```markdown
+- Getting Started with macOS
+- Using the API with npm
+```

data/docs/cops/markdown/list_item_punctuation.md

@@ -0,0 +1,70 @@
+# Markdown/ListItemPunctuation
+
+Requires, forbids, or consistently uses terminal punctuation in parsed Markdown list items. Terminal punctuation is a period, exclamation mark, question mark, or ellipsis. Punctuation characters may differ; for example, a question and a statement are consistent. A closing quotation mark after punctuation is allowed. Inline Markdown formatting does not affect the check.
+
+With `Style: consistent`, the first item sets the expected style. `always` requires terminal punctuation on every checked item, including single-item lists; `never` forbids it. Nested lists are checked independently. The cop reports only and checks a list only when every item consists of one parsed paragraph; items with code blocks, multiple blocks, or other ambiguous structure are skipped.
+
+## Configuration
+
+```yaml
+Markdown/ListItemPunctuation:
+  Enabled: false
+  Style: consistent # consistent, always, or never
+  AllowedPunctuation:
+    - "."
+    - "!"
+    - "?"
+    - "…"
+```
+
+`AllowedPunctuation` restricts the recognized terminal characters (`.`, `!`, `?`, and `…`). Every character in the terminal punctuation sequence must be allowed, so a period-only policy rejects both `.?` and `?.`. It does not introduce new punctuation characters. In `consistent` mode, this restriction applies to punctuated items without requiring punctuation on an entirely unpunctuated list. `never` forbids all recognized terminal punctuation regardless of this setting.
+
+## Example
+
+For this configuration:
+
+```yaml
+Markdown/ListItemPunctuation:
+  Enabled: true
+  Style: always
+```
+
+### Bad
+
+```markdown
+- Build the package
+- Run the tests
+```
+
+### Good
+
+```markdown
+- Build the package.
+- Is it ready?
+```
+
+## Require Periods
+
+For this configuration:
+
+```yaml
+Markdown/ListItemPunctuation:
+  Enabled: true
+  Style: always
+  AllowedPunctuation:
+    - "."
+```
+
+### Bad
+
+```markdown
+- Build the package!
+- Run the tests
+```
+
+### Good
+
+```markdown
+- Build the package.
+- Run the tests.
+```

data/docs/cops/markdown/list_marker_spacing.md

@@ -1,21 +1,25 @@
 # Markdown/ListMarkerSpacing
 
-Enforces spacing after list markers. A list uses its `Multi` setting if any item spans multiple lines, including nested content; otherwise it uses `Single`. Empty items are ignored.
+Enforces one spacing policy for all ordered and unordered list items, whether single-line or multiline. Empty items are ignored when checking spacing.
 
-Autocorrection supports simple one-line items and widths from one to four spaces. Other cases are report-only to preserve item structure.
+The `fixed` style requires exactly `MinSpaces` after every marker. The `aligned` style uses `MinSpaces` after the widest actual sibling marker and adds padding after shorter markers so item text aligns when sibling markers have the same indentation. For bullets, whose markers are all one character wide, both styles require `MinSpaces`.
+
+Nested lists, separate lists, and lists in different containers are evaluated independently. Empty sibling markers contribute to the width even though their spacing is not checked. Alignment uses source markers, not inferred sequence numbers, and works across wider transitions such as `99.` to `100.`.
+
+Autocorrection supports simple one-line items and computed gaps from one to four spaces. Multiline items, items containing nested blocks, and larger gaps are report-only to preserve continuation indentation and item structure. Tabs in a nonempty marker gap are replaced with spaces when correction is safe.
 
 ## Configuration
 
 ```yaml
 Markdown/ListMarkerSpacing:
   Enabled: true
-  UnorderedSingle: 1
-  OrderedSingle: 1
-  UnorderedMulti: 1
-  OrderedMulti: 1
+  Style: fixed
+  MinSpaces: 1
 ```
 
-## Example
+`Style` accepts `fixed` or `aligned`. `MinSpaces` must be a positive integer. The defaults retain one space after every marker.
+
+## Fixed Spacing
 
 ### Bad
 
@@ -30,3 +34,49 @@ Markdown/ListMarkerSpacing:
 - one
 - two
 ```
+
+## Aligned Spacing
+
+For this configuration:
+
+```yaml
+Markdown/ListMarkerSpacing:
+  Style: aligned
+  MinSpaces: 2
+```
+
+### Bad
+
+```markdown
+8. Eight
+9. Nine
+10. Ten
+
+- Bullet
+```
+
+### Good
+
+```markdown
+8.   Eight
+9.   Nine
+10.  Ten
+
+-  Bullet
+```
+
+Each gap is the widest sibling marker width minus the current marker width plus `MinSpaces`. Setting `MinSpaces: 1` produces two spaces after `8.` and `9.` and one after `10.` in this example.
+
+## Migrating From 0.1.0
+
+**Breaking configuration change:** `OrderedSingle`, `OrderedMulti`, `UnorderedSingle`, and `UnorderedMulti` have been removed. RuboCop rejects these keys with migration guidance instead of silently ignoring them.
+
+Replace equal legacy values with `Style: fixed` and that value for `MinSpaces`. For example, four legacy settings all set to `2` become:
+
+```yaml
+Markdown/ListMarkerSpacing:
+  Style: fixed
+  MinSpaces: 2
+```
+
+Different legacy values cannot all be preserved by a single policy; choose the desired shared spacing.

data/docs/cops/markdown/ordered_list_numbering.md

@@ -9,7 +9,7 @@ Autocorrection preserves punctuation. Changes in number width are report-only be
 ```yaml
 Markdown/OrderedListNumbering:
   Enabled: false
-  EnforcedStyle: sequential # Or ones, requiring every marker to be 1.
+  Style: sequential # Or ones, requiring every marker to be 1.
 ```
 
 ## Example
@@ -27,3 +27,12 @@ Markdown/OrderedListNumbering:
 1. one
 2. two
 ```
+
+## Migrating From 0.1.0
+
+Replace `EnforcedStyle` with `Style`:
+
+```yaml
+Markdown/OrderedListNumbering:
+  Style: sequential
+```

data/docs/cops/markdown/proper_names.md

@@ -1,8 +1,8 @@
 # Markdown/ProperNames
 
-Corrects configured names to their canonical capitalization in prose, headings, and tables. Matching is case-insensitive, uses whole-word boundaries, and treats punctuation in names literally.
+Corrects configured names to their canonical capitalization in Markdown. Matching is case-insensitive, uses whole-word boundaries, and treats punctuation in names literally.
 
-Code is checked only when enabled.
+Code spans, code blocks, links, escaped syntax, HTML, and front matter are excluded by default. `CodeBlocks` includes code spans and code-block contents when enabled; fence language labels are never checked. Use [Text/ProperNames](../text/proper_names.md) for literal plain-text files.
 
 ## Configuration
 
@@ -10,7 +10,7 @@ Code is checked only when enabled.
 Markdown/ProperNames:
   Enabled: false
   Names: [] # Canonical spellings; an empty list disables checks.
-  CodeBlocks: false # Set true to check inline code and code blocks, but never fence info strings.
+  CodeBlocks: false # Also check inline code and code-block contents.
 ```
 
 ## Example

data/docs/cops/markdown/raw_html.md

@@ -1,27 +1,120 @@
 # Markdown/RawHtml
 
-Reports HTML elements outside the configured allowlist, including nested elements and table cells. Only opening tags are checked; comments are ignored.
+Reports HTML elements outside the configured allowlist, including nested elements and table cells. Only opening tags are checked; comments are ignored. Element names and attribute names are case-insensitive.
 
-Report-only: removing HTML can discard content or structure.
+`AllowedElements` accepts plain element names and attribute allowlists in the same list. A plain name permits that element with any attributes or none. An attribute list permits zero or more of the listed attributes and rejects every unlisted attribute. Elements not listed are rejected.
+
+This is a lint policy, not an HTML sanitizer or security guarantee. Attribute values are not checked, and no automatic correction is offered.
 
 ## Configuration
 
 ```yaml
 Markdown/RawHtml:
   Enabled: false
-  AllowedElements: [] # Case-insensitive element names without angle brackets.
+  AllowedElements: []
 ```
 
-## Example
+## Examples
+
+### Disallow All HTML
+
+For this configuration:
+
+```yaml
+Markdown/RawHtml:
+  Enabled: true
+  AllowedElements: []
+```
 
-### Bad
+#### Bad
 
 ```markdown
 <b>Important</b>
+
+<img src="chart.png" alt="Results">
 ```
 
-### Good
+#### Good
 
 ```markdown
 **Important**
+
+![Results](chart.png)
+```
+
+### Allow an Element with or Without Attributes
+
+For this configuration:
+
+```yaml
+Markdown/RawHtml:
+  Enabled: true
+  AllowedElements:
+    - br
+    - img
+```
+
+#### Bad: an Unlisted Element
+
+```markdown
+<div>Results</div>
+```
+
+#### Good: Attributes Are Optional and Unrestricted
+
+```markdown
+Text<br>More text.
+
+<img src="chart.png" alt="Results">
+
+<img src="chart.png" alt="Results" width="320" height="200">
 ```
+
+### Allow Only Specific Attributes
+
+For this configuration:
+
+```yaml
+Markdown/RawHtml:
+  Enabled: true
+  AllowedElements:
+    - br
+    - img:
+        - src
+        - alt
+        - width
+        - height
+        - style
+```
+
+#### Bad: an Unlisted Attribute, Even Alongside Allowed Ones
+
+```markdown
+<img src="chart.png" alt="Results" loading="lazy">
+
+<img src="chart.png" width="320" data-note="width=320">
+```
+
+#### Good: Zero or More Allowed Attributes
+
+```markdown
+![Results](chart.png)
+
+Text<br>More text.
+
+<img>
+
+<img src="chart.png" alt="Results">
+
+<img src="chart.png" alt="Results" width="320">
+
+<img src="chart.png" alt="Results" height="200">
+
+<img src="chart.png" alt="Results" style="width: 50%">
+```
+
+### Matching Rules
+
+Each attribute-rule entry maps one element name to a list of permitted attribute names. None are required. An empty attribute list permits only tags with no attributes. Attribute values are not checked: `width="320"` and `width="50%"` are both permitted when `width` is listed. `data-note="width=320"` is rejected unless `data-note` itself is listed.
+
+Each opening tag is checked independently, including nested elements: allowing `img` does not allow a surrounding `div`. If multiple entries match the same element, satisfying any entry is enough; adding a plain `img` entry therefore removes attribute restrictions for `img`. Keep only the attribute-list entry when attributes must be restricted.

data/docs/cops/markdown/reference_definitions.md

@@ -2,7 +2,9 @@
 
 Reports duplicate reference definitions and, when enabled, unused definitions. All link and image reference forms count as uses; IDs ignore case and repeated whitespace. Footnotes are not checked.
 
-Set `AllowIdenticalDuplicates: true` to repeat definitions near their uses while still reporting conflicts. Destinations are compared after decoding Markdown escapes and HTML entities; titles must also match. The first definition still determines the link target. Unused-definition checking remains independent.
+`Duplicates: forbid` reports every duplicate, including identical definitions. Set `Duplicates: allow_identical` to repeat definitions near their uses while still reporting conflicts. Destinations are compared after decoding Markdown escapes and HTML entities; titles must match exactly. The first definition still determines the link target. `Duplicates: allow` permits all duplicates.
+
+Set `Unused: true` to report unused definitions independently of the duplicate policy, including when `Duplicates: allow`. When a definition is both a forbidden duplicate and unused, only the duplicate diagnostic is reported for that definition. `IgnoredDefinitions` exempts normalized IDs from both checks.
 
 Report-only: removing definitions can change link targets or remove comments.
 
@@ -11,9 +13,8 @@ Report-only: removing definitions can change link targets or remove comments.
 ```yaml
 Markdown/ReferenceDefinitions:
   Enabled: true
-  CheckUnused: false
-  CheckDuplicates: true
-  AllowIdenticalDuplicates: false
+  Duplicates: forbid # forbid, allow_identical, or allow
+  Unused: false
   IgnoredDefinitions: # Allow conventional comment-like definitions, using normalized IDs.
     - "//"
 ```
@@ -34,3 +35,28 @@ Markdown/ReferenceDefinitions:
 
 [docs]: /guide
 ```
+
+## Migrating From 0.1.0
+
+Rename `CheckUnused` to `Unused`, keeping its value. Replace `CheckDuplicates` and `AllowIdenticalDuplicates` with `Duplicates`:
+
+- `CheckDuplicates: false`, regardless of `AllowIdenticalDuplicates`: use `Duplicates: allow`.
+- `CheckDuplicates: true` (or omitted) with `AllowIdenticalDuplicates: true`: use `Duplicates: allow_identical`.
+- `CheckDuplicates: true` (or omitted) with `AllowIdenticalDuplicates: false` (or omitted): use `Duplicates: forbid` (the default).
+
+For example, replace:
+
+```yaml
+Markdown/ReferenceDefinitions:
+  CheckDuplicates: true
+  AllowIdenticalDuplicates: true
+  CheckUnused: true
+```
+
+With:
+
+```yaml
+Markdown/ReferenceDefinitions:
+  Duplicates: allow_identical
+  Unused: true
+```

data/docs/cops/markdown/strong_style.md

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

data/docs/cops/markdown/structural_line_length.md

@@ -9,12 +9,9 @@ Use [Prose/MaxLength](../prose/max_length.md) for paragraph formatting. Structur
 ```yaml
 Markdown/StructuralLineLength:
   Enabled: false
-  Max: 80 # Positive character count.
-  Headings: true
-  HeadingMax: null # Inherit Max.
-  CodeBlocks: false
-  CodeBlockMax: null # Inherit Max.
-  Tables: false # Includes delimiter rows when enabled.
+  Headings: 80 # Positive character count, or false to disable.
+  CodeBlocks: false # Positive character count, or false to disable.
+  Tables: false # Positive character count, or false to disable; includes delimiter rows.
 ```
 
 ## Example
@@ -24,7 +21,7 @@ For this configuration:
 ```yaml
 Markdown/StructuralLineLength:
   Enabled: true
-  Max: 12
+  Headings: 12
 ```
 
 ### Bad
@@ -38,3 +35,30 @@ Markdown/StructuralLineLength:
 ```markdown
 # Short
 ```
+
+## Migrating From 0.1.0
+
+Each structural element now has one setting: a positive character count enables that element and sets its limit, while `false` disables it. The shared `Max` setting and separate enable/value pairs have been removed. RuboCop reports obsolete old keys with migration guidance; replace them with a per-element width.
+
+For example, migrate this configuration:
+
+```yaml
+Markdown/StructuralLineLength:
+  Max: 80
+  Headings: true
+  HeadingMax: 120
+  CodeBlocks: true
+  CodeBlockMax: 100
+  Tables: false
+```
+
+To this configuration:
+
+```yaml
+Markdown/StructuralLineLength:
+  Headings: 120
+  CodeBlocks: 100
+  Tables: false
+```
+
+The defaults retain 80-character headings while code blocks and tables remain unchecked.

data/docs/cops/markdown/table_pipes.md

@@ -9,7 +9,13 @@ Autocorrection preserves cell contents. Removing pipes from single-column tables
 ```yaml
 Markdown/TablePipes:
   Enabled: true
-  Style: consistent # consistent, leading_and_trailing, leading_only, trailing_only or no_leading_or_trailing.
+  Style: consistent
+  SupportedStyles:
+    - consistent
+    - leading_and_trailing
+    - leading_only
+    - trailing_only
+    - no_leading_or_trailing
 ```
 
 ## Example

data/docs/cops/markdown/table_spacing.md

@@ -9,7 +9,11 @@ Alignment counts source characters, not display width. Empty cells stay empty.
 ```yaml
 Markdown/TableSpacing:
   Enabled: true
-  Style: aligned # aligned, compact or tight.
+  Style: aligned
+  SupportedStyles:
+    - aligned
+    - compact
+    - tight
 ```
 
 ## Example

data/docs/cops/markdown/thematic_break_style.md

@@ -10,6 +10,8 @@ Markdown/ThematicBreakStyle:
   Style: consistent
 ```
 
+`Style` accepts `consistent`, a literal Markdown thematic break such as `- - -`, or a nonempty array of literal breaks. Each literal must contain at least three matching `*`, `-`, or `_` markers, optionally separated by spaces or tabs, without leading or trailing whitespace. There is no finite `SupportedStyles` list.
+
 ## Example
 
 For this configuration: