eslint-plugin-markdown-preferences-paragraph 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026/11/08)
+
+- [#2](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/2): Add opt-in numeric paragraph wrapping and unwrapping, leaving paragraphs untouched when width is omitted, with data-driven file-fixture, packaged ESLint, and workflow-checker CLI tests - [@dblock](https://github.com/dblock).
+- [#3](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/3): Reflow safe paragraphs to numeric widths even when existing lines fit, preserving hard breaks, literals, containers, and canonical wrapping; reset the unpublished version to 0.1.0 - [@dblock](https://github.com/dblock).
+- [#4](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/4): Replace Markdownlint tooling with ESLint Markdown/style checks, this plugin's single-line paragraph rule, and native CSpell-backed spelling; add actual-configuration file fixtures and retain the reviewed vocabulary - [@dblock](https://github.com/dblock).
+- [#5](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/5): Add an original editable pale blue paragraph-wrap logo, 160-pixel README placement, artwork maintenance guidance, and packaged-asset checks - [@dblock](https://github.com/dblock).
+- [#7](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/7): Add manually dispatched release-it automation for version and changelog preparation, exact-artifact npm trusted publishing, tags and GitHub Releases, recovery artifacts, and the next development version - [@dblock](https://github.com/dblock).
+- [#8](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/8): Prepare installation instructions for the first 0.1.0 release, simplify usage, separate configuration, fixing, and interoperability guidance, and update the README installation pin during releases - [@dblock](https://github.com/dblock).
+- [#10](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/10): Rename the unpublished package and repository to eslint-plugin-markdown-preferences-paragraph, use the paragraph/paragraph-wrap namespace in examples and fixtures, and correct the staged npm bootstrap sequence - [@dblock](https://github.com/dblock).
+- [#11](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/11): Rename the exported rule to wrap for paragraph/wrap configuration, including the project's own Markdown linting, documentation, and file fixtures before the first publication - [@dblock](https://github.com/dblock).

package/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Read [Design](DESIGN.md) and [Automated Contributor Instructions](AGENTS.md). The rule supports numeric wrapping and unwrapping through one paragraph-wide policy.
+
+## Setup and Validation
+
+Use Node.js `26.13.0` from `.nvmrc` for development and npm. The package supports Node.js `^22.13.0 || >=24.0.0`, ESLint `^9.39.0 || ^10.0.0`, and `@eslint/markdown ^8.0.0`. Documentation spelling tools require Node.js 22.18 or later; the compatibility test matrix exercises the package's lower runtime minimum without running those tools there. Recheck stable releases when selecting or updating dependencies while preserving supported-runtime compatibility.
+
+```sh
+npm ci
+npm test
+npm run lint
+npm run test:coverage
+npm run package:check
+```
+
+Run `npm test` and `npm run lint` before every push, including updates to a PR. Run final checks before committing and reuse results for the push when tested content/configuration has not changed. Validate packaging/public-entry-point changes with the packaged CLI fixture suite: it creates an archive with `npm pack`, inspects its contents, installs that exact archive in a temporary consumer, and runs the real ESLint CLI. `npm test` already runs this suite; `npm run package:check` selects it alone, so do not immediately repeat it after a passing full test run.
+
+`npm run lint:code` checks source and embedded JavaScript examples. `npm run lint:markdown` separately uses ESLint for Markdown structure, prose, spelling, single-line paragraphs, and title-case headings. It combines `@eslint/markdown`, `eslint-plugin-markdown-preferences`, this plugin with `width: "nowrap"`, and native ESLint documentation rules backed by public CSpell dictionary/text APIs. No Markdownlint tools are installed or invoked. `npm run lint:workflows` parses YAML and checks title case only for workflow, job, and step display names. Machine identifiers, expressions, and arbitrary `name` fields are not capitalization targets.
+
+Keep human-readable Markdown headings and YAML display names in title case, preserving proper names and code identifiers. Keep each Markdown prose paragraph on one source line. Review `.spellcheck.txt` additions and fix typos instead of adding them to the dictionary. Intentionally invalid file fixtures are not project documentation.
+
+Test, Lint, and Package have separate CI workflows. Tests cover minimum/current Node versions and supported ESLint majors using explicit inline `matrix.entry` records without `include`/`exclude`; a current-Node coverage job reports to Coveralls. ESLint 9 compatibility is retained for existing Markdown setups while development and lint use current ESLint 10. No Danger checks are configured for this JavaScript project.
+
+## Tests
+
+Run focused API fixture tests with `node --test test/plugin.test.js` or the packed CLI suite with `npm run package:check`. `node --test test/documentation.test.js` loads the actual ESLint configs against file fixtures for headings, prose wrapping, spelling and original Unicode offsets, structural errors, first headings/final newlines, fixture exclusions, and embedded JavaScript. Native Markdown/spelling fixtures require Node 22.18 or later and are skipped below that development-tool minimum; package API/CLI tests still cover Node 22.13. Tests also exercise the YAML display-name checker.
+
+`node --test test/release.test.js` checks project-owned changelog fixtures, unsafe version inputs, metadata guards, and registry errors. One isolated integration uses real release-it and local Git with simulated npm publication to check that the validated archive is published once and the next development version is prepared; it does not retest the dependency's failure matrix. CLI/integration checks require release-it's supported runtime; the workflow uses Node 26.13.0. The `PARAGRAPH_WRAP_PACKAGE_ARCHIVE` environment variable selects an existing release tarball for the packed-consumer suite, preserving the artifact validated for publication.
+
+Both API and CLI tests use the same [data-driven file fixtures](DESIGN.md#data-driven-file-fixtures): metadata, original Markdown, expected fixed Markdown, and stable before/after diagnostics. The CLI suite uses the actual packed plugin with the matrix-selected ESLint version, compares exact bytes and exit status, and verifies second-pass stability without mutating checked-in fixtures. Add cases through fixture files, not case-specific runner branches. Preserve CRLF/mixed endings through `.gitattributes` and the missing-final-newline fixture's bytes. Add focused helper tests only for behavior that is not clearly expressed by file fixtures.
+
+## Pull Requests
+
+For artwork changes, follow [Logo Maintenance](DESIGN.md#logo). Keep the editable SVG, license/provenance, descriptive alternative text, and 160-pixel README placement. Inspect full-size and light/dark README rendering; `npm test` checks that the real installed archive retains the logo. Keep generated previews outside the repository.
+
+Keep the primary checkout on `master`; use a separate worktree and `<username>/<topic>` branch for each PR. For example, after inspecting existing branches and worktrees:
+
+```sh
+git worktree add -b dblock/implementation ../eslint-plugin-markdown-preferences-paragraph-implementation master
+```
+
+Preserve unrelated work. Prefer one coherent commit per PR and squash multiple topic-branch commits before pushing. Squash-merge PRs; do not use merge commits. Do not push development changes directly to `master`, force-push `master`, amend without approval, or merge/publish/tag without explicit authorization. If a prerequisite PR remains open, obtain the appropriate stacked-PR workflow before creating a dependent PR.
+
+Update affected documentation and add CHANGELOG entries for features, improvements, and fixes, but not minor typos or the initial scaffold. Use `- [#123](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/pull/123): Description - [@dblock](https://github.com/dblock).` with the actual PR number and contributor. Append entries chronologically above `- Your contribution here.` in the Next section. Predict the PR number before opening when reliable, then verify it and correct mismatches without unauthorized amending or force-pushing.
+
+Feature additions increment minor versions in the same PR: reset patch for `0.x`, preserve patch for `1.x` and later. Ask whether to bump major for breaking changes. Synchronize the package manifest and lockfile; see [Releasing](RELEASING.md).
+
+Include the Copilot co-author trailer in AI-assisted commits and disclose AI authorship on behalf of `@dblock` in PRs/comments. Link related issues with closing references; leave them open until the PR merges. State actual validation and pending CI honestly.
+
+The authorized manual release workflow is the sole direct-push exception: release-it publishes the validated npm archive through OIDC, atomically pushes the release commit/tag, creates a GitHub Release, and validates/pushes the next development version. Project hooks format the changelog, validate the exact archive and metadata, and verify pushed refs and registry integrity. Publication precedes the Git push, so a later failure requires recovery rather than an automatic rerun. It never runs on PR merges, has no dry-run input, and requires the `release` environment restricted to `master`. The no-App setup removes the platform PR requirement for all writers, not only Actions; force-push and branch-deletion protections remain active. Ordinary development stays PR-based. Opening or merging its setup PR does not authorize dispatching publication; follow [Releasing](RELEASING.md).
+
+After merging, fetch with pruning, verify the merged state of the PR on GitHub, and inspect its worktree for dirty/untracked files and dependent PRs. Remove only clean, no-longer-needed topic worktrees with `git worktree remove`, then delete their local branches. If squash ancestry requires `git branch -D`, first verify that no unmerged or dependent work would be lost. Never remove `master`, active PR branches, or dirty worktrees. Prune stale worktree metadata, verify cleanup, and report blocked cleanup.

package/DESIGN.md

@@ -0,0 +1,238 @@
+# Design
+
+**Status:** First implementation of the agreed scope; not published yet. Research checked on November 8, 2026.
+
+## Purpose
+
+Create `eslint-plugin-markdown-preferences-paragraph`, an independent, opt-in ESLint plugin that checks and safely fixes Markdown paragraph wrapping. Support both positive numeric widths and `"nowrap"` in one `wrap` rule, without becoming a general Markdown formatter.
+
+[To Wrap or Not to Wrap in Markdown?](https://code.dblock.org/2021/06/07/to-wrap-or-not-to-wrap-in-markdown.html) motivates one source line per paragraph: arbitrary reflow can turn a small wording edit into changes across several lines. This is a source-format preference, not a guarantee that all Markdown renderers treat soft line breaks identically.
+
+## Inventory
+
+The article names four existing enforcement tools and an ESLint proposal. `MD013` is also relevant because the article explicitly disables it. Formatters are distinguished from lint rules below.
+
+| Tool | Configuration and Default | Numeric Wrapping | Unwrapping | Implication |
+| --- | --- | --- | --- | --- |
+| [markdownlint-rule-single-line-paragraphs](https://github.com/dblock/markdownlint-rule-single-line-paragraphs) | Enable the custom `single-line-paragraphs` rule; no width setting. | Not supported. | Reports soft-wrapped paragraph segments and supplies coordinated joining/deletion fixes. | Strong precedent for narrow, paragraph-only enforcement, but not a combined wrap/unwrap API. |
+| [markdownlint `MD013` / `line-length`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md) | `line_length: 80`; headings, code blocks, and tables included by default; `strict` and `stern` default to `false`. | Reports overlong lines; documentation recommends splitting them. No automatic paragraph reflow. | Not supported. | A length constraint is not a wrapping preference. Disable `MD013` when using unrestricted single-line paragraphs; simply setting a huge limit is not unwrapping. |
+| [RuboCop `Prose/MaxLength`](https://github.com/dblock/rubocop-prose/blob/main/docs/cops/prose/max_length.md) | Enabled by default; `Max: false` means unwrapping, not disabling. `IgnoreURLs: true`. | A positive `Max` wraps prose, including container prefixes in the character budget. | `Max: false` joins soft line breaks. | Closest existing lint-rule precedent for combining both modes. Its [structural line-length cop](https://github.com/dblock/rubocop-prose/blob/main/docs/cops/markdown/structural_line_length.md) separates non-paragraph limits. |
+| [Prettier](https://prettier.io/docs/options#prose-wrap) | `proseWrap: "preserve"` by default; `printWidth: 80`. | `"always"` reflows prose toward `printWidth`, which is a formatting target rather than an absolute maximum. | `"never"` puts prose blocks on one source line. | Separates wrapping policy from width. `--check` enforces all Prettier formatting, not just paragraph wrapping; `"preserve"` does not unwrap existing text. |
+| [mdformat](https://mdformat.readthedocs.io/en/stable/users/configuration_file.html) | `wrap = "keep"` by default; also accepts `"no"` or an integer. | An integer requests wrapping. | `"no"` requests unwrapping. | Direct precedent for a width-or-keyword setting. Check/write modes also apply other formatting choices; CommonMark is the default, with extensions needed for additional dialects. |
+| [eslint-plugin-markdown-preferences `max-len`](https://ota-meshi.github.io/eslint-plugin-markdown-preferences/rules/max-len.html) | Paragraph default `120`; accepts numeric limits or `"ignore"`, with container overrides and `ignoreUrls: true`. | Reports overlong source lines; the current rule has no fixes. | Not supported in the current rule. | Existing paragraph ownership overlaps this plugin unless users explicitly disable those limits. |
+
+### Syntax and Exemption Differences
+
+The markdownlint custom rule covers root, list, and blockquote paragraphs. It permits hard breaks from two or more trailing spaces or an unescaped trailing backslash, plus line-boundary `<br>`, `<br/>`, and `<br />` tags. Its README excludes headings, code blocks, tables, HTML blocks, front matter, and definitions; it does not advertise footnote-definition paragraph coverage.
+
+`Prose/MaxLength` supports Markdown and plain text, preserves nesting, inline syntax, and hard breaks including `<br>`, and can report without correcting indented paragraphs or unbreakable overlong tokens. Its URL exemption is documented as paragraph lines containing only one URL. In contrast, ESLint's existing `max-len` exempts a line containing a recognized URL anywhere when `ignoreUrls` is enabled. These are materially different policies, not interchangeable options.
+
+`MD013` has its own long-token exceptions: normal mode permits lines with no whitespace beyond the limit, `strict` removes that exception, and `stern` permits unbreakable lines while reporting lines that could be split. Link/image definitions and standalone link/image lines have additional exemptions. These policies should not be silently imported into a new ESLint rule.
+
+Prettier and mdformat are useful behavioral references, not implementation dependencies. Their broader formatting scope and default preservation modes differ from a focused ESLint diagnostic and fix.
+
+## Upstream Direction
+
+[Issue #338](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/issues/338) initially proposed `single-line-paragraphs` without options. The [maintainer response](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/issues/338#issuecomment-6646164240) instead favors `paragraph-wrap` owning both maximum paragraph width and unwrapping, using the term `"nowrap"` and eventually removing paragraph checking from `max-len`.
+
+The [latest proposal](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/issues/338#issuecomment-6665919201) presents two alternatives: introduce `paragraph-wrap` and migrate paragraph ownership, or extend `max-len` without deprecation. The issue remains open; neither alternative should be described as accepted or released. [PR #332](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/pull/332) remains open and unmerged and contains earlier unwrapping work.
+
+This project follows the separate `paragraph-wrap` direction but cannot deprecate, change, or disable another package's rule. It must document coexistence honestly. Any reuse of upstream code or fixtures requires reviewing their license and retaining applicable notices; this proposal does not assume a private upstream utility is a supported API.
+
+## Proposed Public API
+
+Use the repository and npm package name `eslint-plugin-markdown-preferences-paragraph`, under GitHub owner `dblock`. Before this pre-release rename on November 8, 2026, the GitHub repository lookup found no repository, and npm returned `E404` for the unscoped package name; these checks suggest availability but do not reserve the names or guarantee registry acceptance.
+
+Export one ESM plugin object with `meta` and `rules.wrap`. Register it as `paragraph` to use `paragraph/wrap`; the namespace is an ESLint configuration alias, not part of the exported rule name. There is no standalone CLI, replacement parser, fork of the upstream plugin, or automatic activation of unrelated rules.
+
+### Options
+
+| Option | Accepted Values | Proposed Default |
+| --- | --- | --- |
+| `width` | Positive integer, `"nowrap"`, or `"ignore"` | `"ignore"`; omitting `width` leaves paragraphs untouched. |
+
+Reject zero, negative or fractional widths, unsupported keywords, unknown properties, and incorrect types through the rule schema. `"ignore"` skips enforcement; ESLint severity `"off"` disables the entire rule.
+
+Apply the same `width` to every paragraph, including paragraphs inside lists, blockquotes, and supported footnote definitions. The first version has no container-specific overrides or policy precedence. This deliberately simplifies the latest upstream proposal while retaining paragraph coverage in all supported containers.
+
+There is no `ignoreUrls` option or URL-line exemption. Wrap surrounding prose at safe boundaries while keeping URLs intact. If an indivisible URL exceeds the configured width, report without fixing rather than splitting it or ignoring the entire line. URLs need no exception in `"nowrap"` mode.
+
+Do not ship an opinionated recommended preset in the first version. Enable the rule explicitly, and set `width: "nowrap"` for the user's preferred single-line prose or a positive integer for numeric wrapping. Enabling the rule without a `width`, including with an empty options object, does nothing.
+
+### Example Configuration
+
+The public consumer configuration is:
+
+```js
+import markdown from "@eslint/markdown";
+import paragraph from "eslint-plugin-markdown-preferences-paragraph";
+
+export default [
+  {
+    files: ["**/*.md", "**/*.markdown"],
+    plugins: {
+      markdown,
+      paragraph,
+    },
+    language: "markdown/gfm",
+    rules: {
+      "paragraph/wrap": [
+        "error",
+        { width: "nowrap" },
+      ],
+    },
+  },
+];
+```
+
+For numeric wrapping, use `{ width: 120 }`. Container-specific settings and `ignoreUrls` are not supported in the first version.
+
+### Coexistence With Existing Length Rules
+
+When also using `markdown-preferences/max-len`, explicitly ignore paragraph limits at the root and in every supported container. Numeric container settings must be replaced with entity-specific objects so they cannot reintroduce paragraph limits:
+
+```js
+const nonParagraphLimits = {
+  heading: 80,
+  table: 120,
+  html: 120,
+  code: "ignore",
+  frontmatter: "ignore",
+  math: "ignore",
+  paragraph: "ignore",
+};
+
+const maxLenOptions = {
+  ...nonParagraphLimits,
+  list: { ...nonParagraphLimits },
+  blockquote: { ...nonParagraphLimits },
+  footnoteDefinition: { ...nonParagraphLimits },
+  ignoreUrls: true,
+};
+
+// Add this to an existing configuration that registers markdown-preferences.
+export const rules = {
+  "markdown-preferences/max-len": ["error", maxLenOptions],
+};
+```
+
+Adapt existing non-paragraph limits rather than replacing deliberate project policies with these example values. With unrestricted `"nowrap"`, disable markdownlint `MD013`; align any formatter with the same wrapping policy. The plugin neither reads other rules' configuration nor guarantees conflict-free behavior under incompatible settings. A standalone companion cannot provide the maintainer's preferred exclusive ownership until upstream changes are released.
+
+## First-Version Behavior
+
+Check actual paragraph AST nodes at the document root and inside lists, blockquotes, and footnote definitions when the selected language parses them. Support CommonMark and GFM through `@eslint/markdown`, including task lists and GFM footnotes. Compatibility with `markdown-preferences/extended-syntax` is an optional integration, not a reason to create another parser.
+
+In `"nowrap"` mode, report each soft-wrapped segment and join safe line boundaries with one space, without imposing any maximum length. Preserve existing intraline spacing and source spelling. A segment is the part of a paragraph between intentional hard-break boundaries.
+
+In numeric mode, greedily reflow safely editable segments at safe whitespace boundaries to the configured width, including segments whose existing lines already fit. Increasing width from `30` to `80` therefore fills wider lines; decreasing it wraps them more narrowly. Leave already canonical wrapping unchanged. Count indentation, quote/list/footnote prefixes, and inline Markdown syntax in the source width, not rendered text width. Match upstream's documented implementation convention: Unicode display width with four-column tab stops, while preserving original UTF-16 offsets for ESLint fixes.
+
+Keep the existing `width` diagnostics for overlong lines. When all lines fit but a proven safe reflow would change the segment, report one fixable `reflow` diagnostic at its first line. Do not invent a reflow diagnostic when a safe correction cannot be established; overlong lines still report without a fix when unsafe or impossible to correct.
+
+Do not split words, URLs, link/image syntax, inline code, or other indivisible constructs to satisfy a width. URLs do not exempt surrounding prose from wrapping. If an atomic construct cannot fit, retain a diagnostic without an unsafe or endlessly repeated fix.
+
+Preserve two-space and backslash hard breaks, and case-insensitive `<br>`, `<br/>`, and `<br />` at either side of a source-line boundary. Do not interpret an escaped tag or a tag inside inline code as HTML. Keep hard-break spelling and boundaries unchanged and process the remaining soft-wrapped segments independently.
+
+Leave headings, tables, code blocks, HTML blocks, parsed front matter, link definitions, and math blocks alone. This promise depends on the selected parser recognizing those constructs: document the required front-matter/math language options, and do not claim unsupported dialect syntax is automatically protected.
+
+Remove only proven continuation indentation and container prefixes when joining. Preserve first-line markers, task checkboxes, list numbering, blockquote nesting, paragraph boundaries, blank lines, and LF/CRLF style. New numeric-wrap lines must use valid continuation prefixes, never repeated list-item markers.
+
+Report without fixing when safety cannot be established, including multiline literals, ambiguous indentation, directive boundaries, unknown extension syntax, mixed line endings in an edited segment, or a proposed line break that would create a heading, list, blockquote, thematic break, code block, or HTML block. No whole-document serialization or unrelated whitespace cleanup.
+
+## Integration and Implementation
+
+The rule uses the host's paragraph AST, source ranges, ancestry, and original source text. It traverses public AST children rather than importing upstream internal helpers. One rule contains local helpers for display width, segments, proven container prefixes, whitespace boundaries, greedy numeric reflow, and safe edits.
+
+ESLint's public rule context exposes language options but not the active language object or dialect name. The implementation therefore finds the public `@eslint/markdown` languages whose parses reproduce the original document AST, then requires each proposed edit to preserve that AST under every matching language. It normalizes only soft-break whitespace in text values and discards positions; literal values, inline syntax, hard breaks, and block structure must remain equal. It does not inspect other rules' configuration or import an internal parser.
+
+This deliberately favors safety over fixing coverage. If no public dialect matches the original AST, diagnostics remain report-only throughout the file. Standard syntax under the optional extended language can be fixed when it matches; custom containers and other unmatched extension nodes are report-only. Multiline literals, inline comments, directive-boundary patterns, tab-indented prefixes, and ambiguous edited line endings also prevent fixes. A numeric segment containing an overlong atomic construct receives no partial reflow because the whole proposed correction must be compliant and stable.
+
+Both source/API and packaged CLI file fixtures provide behavioral safety evidence. AST equivalence alone is not proof that every renderer treats soft line breaks identically.
+
+Fixes must be non-overlapping and stabilize on a subsequent ESLint pass. A segment that cannot be made compliant safely remains report-only. Use deterministic diagnostics and localized replacement ranges.
+
+### Dependencies and Layout
+
+Use JavaScript ESM, npm with a committed `package-lock.json`, and `node --test`. The package has `src/index.js`, `src/rules/wrap.js`, `test/`, shared test support under `test-support/`, and integration file fixtures. Public exports and an explicit packaged-file list exclude development support from the archive.
+
+Registry checks currently report ESLint `10.14.0`, `@eslint/markdown` `8.0.3`, `eslint-plugin-markdown-preferences` `0.43.0`, and `string-width` `8.3.0`; the Node distribution index reports Node `26.13.0` as the latest stable release and LTS. These are research observations, not permanent pins; recheck stable versions during scaffolding.
+
+Use ESLint `^9.39.0 || ^10.0.0` and `@eslint/markdown ^8.0.0` as peer dependencies, with `string-width` as a direct runtime dependency. `eslint-plugin-markdown-preferences` is a development dependency for coexistence/extended-syntax integration tests; consumers need it only for those optional integrations. Supported Node versions start at `^22.13.0 || >=24.0.0`, matching the selected host's minimum on the supported Node 22 line rather than adding the older Node 20 line solely because upstream still allows it. Test the minimum supported Node version and the latest stable development runtime, plus both supported ESLint major versions. Use Node.js `26.13.0` for development; documentation spelling tools require at least Node.js 22.18.
+
+Development linting uses ESLint throughout JavaScript and Markdown. `@eslint/markdown` checks document structure and processes embedded JavaScript; `eslint-plugin-markdown-preferences` supplies Markdown style and title-case checks; this package's public export enforces single-line prose with `width: "nowrap"`. The historical Markdownlint tools in the inventory above are research references, not installed dependencies or active checks. Markdown-source linting and code-block processor linting use separate ESLint invocations because applying the processor replaces the original Markdown input. A small tested YAML-aware checker enforces title case for workflow/job/step display names without checking machine identifiers or arbitrary `name` fields. Test, Lint, and Package workflows remain separate, with coverage and Coveralls.
+
+Native Markdown spelling uses a local ESLint rule backed by public `cspell-lib` dictionary and text-extraction APIs, with US English, software terminology, and the existing `.spellcheck.txt` vocabulary. CSpell's ESLint plugin currently visits only JavaScript `Program` nodes, so enabling it on the Markdown AST would silently skip prose. The native rule checks text nodes rather than URLs or inline/fenced code, preserves original UTF-16 source offsets, and never rewrites spelling or mutates third-party rules/ASTs. Two small native rules retain first-level-one-heading and final-newline checks; comments and standalone logo images may precede the heading. HTML allowances are limited to `img` elements. The style configuration keeps the prior allowance for both Markdown hard-break forms and unaligned table columns.
+
+Documentation file fixtures load the actual Markdown and embedded-code ESLint configs and verify valid/invalid headings, spelling and Unicode locations, public `wrap` fixes, structural errors, final-newline fixes, ignored test fixtures, and literal/code exclusions. These development-tool checks require Node 22.18 or later, independently of the package's lower runtime minimum.
+
+## Release Automation
+
+A manually dispatched GitHub Actions workflow uses development-only `release-it` for version updates, Git commits/tags/pushes, npm trusted publishing, and GitHub Release creation. Project hooks retain the existing handwritten changelog format and validate the exact artifact. Dispatch releases the checked-in stable version unless an explicit stable-version override is supplied. It does not infer versions from conventional commits or publish on merges, and it has no dry-run input.
+
+Release-it 21.1.2 supports the release runtime but its proxy chain selects an outdated FTP client. A scoped `get-uri` override selects stable `basic-ftp` 6.2.6 to address the reported directory-listing denial of service; its public Client methods used by `get-uri` are retained. This release workflow uses HTTPS, not FTP. Recheck and remove the override when the upstream dependency includes the fix.
+
+The hooks reject dirty checkouts, mismatched metadata, empty notes, existing registry versions/tags, unexpected file changes, and concurrent default-branch updates. They pack once to `.release/package.tgz` and run the existing real CLI consumers against that exact archive; `npm.publishPath` lets release-it publish the retained file without replacing it. `npm.skipChecks` avoids token-based authentication checks that cannot validate OIDC. The native flow publishes npm first, then commits/tags and atomically pushes Git without force. A pre-GitHub-Release hook verifies the remote commit/tag and registry integrity, because release-it can report a Git push failure without throwing after npm succeeds.
+
+The clean-check hook replaces `git.requireCleanWorkingDir`, disabling native source-reset and local-tag rollback handlers without allowing a dirty starting checkout. Successful native npm publication prevents release-it from attempting remote-tag rollback on a failed Git push; the next-version run disables tagging altogether. Failures retain the archive, checksum, and metadata patch in Actions artifacts rather than maintaining custom state or Git bundles. Never roll back published packages or delete release tags.
+
+After successful npm publication and GitHub Release creation, a second release-it run increments patch, opens a new Next section through its changelog hook, runs tests and lint against that next version, and commits/pushes its metadata. This run disables npm publication, GitHub Releases, and Git tags; it does not repeat the release hooks. Ordinary development remains PR-based. The explicitly approved no-App setup allows direct default-branch pushes for all repository writers while retaining force-push/deletion protections; the release environment is restricted to `master`. See [Releasing](RELEASING.md) for the one-time npm bootstrap, trusted-publisher configuration, invocation, and failure recovery.
+
+## Acceptance Tests
+
+| Area | Required Evidence |
+| --- | --- |
+| Modes and schema | Wrap/unwrap/ignore with the same width across root and nested paragraphs; invalid settings, including container-specific options and `ignoreUrls`, rejected; opt-in activation. |
+| Containers | Ordered/unordered and task lists, nested quotes/lists, lazy continuations, loose paragraphs, and footnotes under a supporting language; markers and structure unchanged. |
+| Breaks and inline syntax | Both Markdown hard-break forms; HTML breaks on either side of a boundary; escaped tags/backslashes; links, images, emphasis, inline code, Unicode, and literal content. |
+| Numeric limits | Prefix-inclusive widths, tabs and wide/combining characters; prose wraps around intact URLs; overlong indivisible URLs and other constructs report without fixes; widening and narrowing reflow existing wrapping; canonical paragraphs unchanged; no partial-fix loops. |
+| Conservative fixes | Multiline literals, directive boundaries, ambiguous indentation, unknown extensions, and syntax-changing split points produce diagnostics without unsafe edits. |
+| Exclusions and stability | Non-paragraph blocks unchanged; configured front matter and math; LF/CRLF preservation; no fix overlap; a second fix pass makes no further changes. |
+| Real integration | ESLint CLI check and `--fix` with CommonMark/GFM, optional extended syntax, inline disable comments, and actual `max-len` coexistence configuration. |
+| Packaged consumer | Install the actual `npm pack` artifact in an owned temporary consumer; import public exports and run ESLint against fixtures without source-tree dependencies. |
+
+### Data-Driven File Fixtures
+
+Drive integration tests from checked-in fixture directories rather than Markdown strings embedded in test code. Each directory is one named case, discovered in sorted order by a shared `node --test` runner:
+
+```text
+test/fixtures/integration/
+  nowrap-list/
+    case.json
+    input.md
+    expected.md
+    diagnostics.json
+  numeric-url/
+    case.json
+    input.md
+    expected.md
+    diagnostics.json
+```
+
+`case.json` declares the language (`commonmark`, `gfm`, or optional `extended-syntax`), language options, rule options, and whether to enable the existing `max-len` coexistence configuration. Optional metadata selects severity, an `.md`/`.markdown` consumer filename, or expected configuration failure. The shared loader validates metadata and diagnostic fields so misspellings cannot silently skip coverage. Run each case under its declared dialect; do not indiscriminately apply GFM fixtures to CommonMark.
+
+`input.md` is the original file; `expected.md` is the exact file after fixing. For valid and report-only cases, expected output is identical to input. Check in expected bytes rather than deriving them from the implementation. `diagnostics.json` records expected diagnostics before and after fixing using message ID, start line/column, and fix availability; optional rule ID/severity override defaults of this plugin's rule and error severity. Do not snapshot temporary absolute paths, raw fix ranges, or unrelated CLI metadata.
+
+The CLI runner inspects and installs the actual packed plugin in an owned temporary consumer with the matrix-selected ESLint and matching host versions. It generates flat configuration from fixture metadata using public plugin exports. It reuses that installation across cases but copies each input into an isolated case directory before invoking the real ESLint CLI. It never runs `--fix` against checked-in fixtures or imports the plugin from the source checkout. A separate public-API runner exercises the same fixtures against source for focused checks and coverage. Process invocations use argument arrays and capture output and exit status.
+
+For every case, run a check with JSON output and compare diagnostics and the expected success/failure status. Then run `--fix`, compare the resulting Markdown byte-for-byte with `expected.md`, and compare remaining diagnostics. Finally run `--fix` again and assert unchanged bytes and diagnostics. Report-only cases may still exit with lint errors; that is expected, not a runner failure. Assert that check-only invocations leave files unchanged.
+
+Start with fixtures covering root prose, ordered/unordered/task lists, nested quotes and lists, footnotes, hard-break segments, inline markup and literals, URL-adjacent prose and overlong URLs, numeric split points that would change parsing, ignored widths, excluded blocks, inline disable comments, and `max-len` coexistence. Add invalid-option cases with expected configuration failure and unchanged input, without depending on full ESLint error wording. Exercise Unicode and tabs in file fixtures, not only helper unit tests.
+
+Include LF and CRLF cases and a missing-final-newline case. Preserve fixture bytes with narrowly targeted `.gitattributes` entries such as `-text` for CRLF and mixed-ending fixtures so Git checkout cannot invalidate the line-ending assertions. Mixed-ending edits that cannot be proven safe should remain report-only. Keep intentionally invalid fixtures out of project documentation linting without excluding normal documentation.
+
+Use focused helper tests only for behavior that cannot be expressed clearly through file fixtures. New end-to-end behavior should normally require adding or updating a fixture, not adding a case-specific branch to the runner. Fixture failures must identify the case and phase and show a concise diagnostic or file diff.
+
+## Logo
+
+[`assets/logo.svg`](assets/logo.svg) is original artwork created by GitHub Copilot for this project from the approved notepad-and-wrap-arrow concept, refined to a softer pale blue palette with a thin border. It uses the project's [MIT license](LICENSE); no third-party logos, fonts, or images were adapted.
+
+The SVG is both the editable source and the README display asset. Its transparent 256-by-256 canvas contains a pale blue notepad, a lightly shaded folded corner, a thin blue border, and muted blue paragraph lines with a returning wrap arrow. The README places it above the title at 160 pixels wide, with descriptive alternative text and blank lines separating the logo, title, and badges.
+
+Edit the SVG paths and colors directly; no generator, font, or raster conversion is required. Preserve the view box, accessible title/description, transparent background, and clear geometry at the README display size. Keep previews outside the package and repository. Inspect the full-size SVG and rendered README at 160 pixels on light and dark backgrounds for legibility and clipping; run `npm run lint` and `npm test`. The packed-consumer suite verifies that the exact editable logo is installed with the README.
+
+## Scope and Review Gates
+
+The first implementation includes numeric wrapping and `"nowrap"` together, one width policy for all paragraphs, safe fixes, documentation, and real host/package tests. Non-goals are container-specific policies, upstream deprecation work, a full Markdown formatter, semantic sentence wrapping, MDX or arbitrary renderer support, and automatic cross-rule conflict resolution.
+
+The agreed first-version scope combines numeric wrapping and `"nowrap"`, with no checks when `width` is omitted, no container-specific options, and no URL exemptions. The scaffold PR has merged, and this implementation is the next focused PR.
+
+Validate and open the implementation PR from its separate worktree, then pause for explicit approval. No additional merging, publication, release tags, or artwork is authorized.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dblock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+<img src="assets/logo.svg" alt="Pale blue notepad with a thin border and a paragraph-wrap arrow" width="160">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# ESLint Plugin Markdown Preferences Paragraph
+
+[![Test](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/actions/workflows/test.yml/badge.svg)](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/actions/workflows/test.yml) [![Lint](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/actions/workflows/lint.yml/badge.svg)](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/actions/workflows/lint.yml) [![Package](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/actions/workflows/package.yml/badge.svg)](https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/actions/workflows/package.yml) [![Coverage](https://coveralls.io/repos/github/dblock/eslint-plugin-markdown-preferences-paragraph/badge.svg?branch=master)](https://coveralls.io/github/dblock/eslint-plugin-markdown-preferences-paragraph?branch=master)
+
+An ESLint plugin for checking and safely fixing Markdown paragraph wrapping, inspired by [eslint-plugin-markdown-preferences#338](https://github.com/ota-meshi/eslint-plugin-markdown-preferences/issues/338).
+
+## Installation
+
+```sh
+npm install --save-dev eslint @eslint/markdown eslint-plugin-markdown-preferences-paragraph@0.1.0
+```
+
+Requires Node.js 22.13 or a supported newer version, ESLint 9.39 or 10.x, and `@eslint/markdown` 8.x.
+
+## Usage
+
+In `eslint.config.js`:
+
+```js
+import markdown from "@eslint/markdown";
+import paragraph from "eslint-plugin-markdown-preferences-paragraph";
+
+export default [{
+  files: ["**/*.md"],
+  plugins: { markdown, paragraph },
+  language: "markdown/gfm",
+  rules: {
+    "paragraph/wrap": ["error", { width: 80 }],
+  },
+}];
+```
+
+Check Markdown paragraphs against an 80-column width:
+
+```sh
+npx eslint "**/*.md"
+```
+
+## Configuration
+
+The rule accepts one option, `width`:
+
+| Value | Behavior |
+| --- | --- |
+| Positive integer, such as `80` | Check paragraph width and safely reflow to that width. |
+| `"nowrap"` | Check for soft line breaks and safely join them without a width limit. |
+| `"ignore"` | Skip paragraph checks and fixes. |
+| Omitted (default) | Skip paragraph checks and fixes. |
+
+One width policy applies to every paragraph, including paragraphs in lists, blockquotes, and GFM footnotes. There are no container-specific widths, URL exemptions, or recommended presets.
+
+Numeric widths include source markup and container prefixes, Unicode display width, and four-column tab stops.
+
+## Fixing
+
+Apply safe paragraph fixes with ESLint:
+
+```sh
+npx eslint "**/*.md" --fix
+```
+
+Numeric widths reflow paragraphs to the configured width; `"nowrap"` joins soft line breaks. Intentional hard breaks remain separate, and words, URLs, and inline constructs are never split. Unsafe or impossible corrections report without a fix; see [Fix Safety](DESIGN.md#integration-and-implementation).
+
+Safe paragraph segments reflow even if their existing lines already fit: changing `width` from `30` to `80` fills the wider lines when fixing. Already canonical wrapping stays untouched.
+
+## Interoperability
+
+### [`markdown-preferences`](https://github.com/ota-meshi/eslint-plugin-markdown-preferences)
+
+With the plugin registered as `markdownPreferences`, configure `max-len` to skip paragraphs at the root and in containers. For example, retain an 80-column heading limit:
+
+```json
+{
+  "markdownPreferences/max-len": ["error", {
+    "heading": 80,
+    "paragraph": "ignore",
+    "list": { "paragraph": "ignore" },
+    "blockquote": { "paragraph": "ignore" },
+    "footnoteDefinition": { "paragraph": "ignore" }
+  }]
+}
+```
+
+### [markdownlint](https://github.com/DavidAnson/markdownlint)
+
+Disable markdownlint `MD013` when enforcing unrestricted `"nowrap"`. In `.markdownlint.json`:
+
+```json
+{
+  "MD013": false
+}
+```
+
+## Contributing
+
+Read [Contributing](CONTRIBUTING.md), [Design](DESIGN.md), [Changelog](CHANGELOG.md), [Releasing](RELEASING.md), and [Automated Contributor Instructions](AGENTS.md).
+
+## License
+
+[MIT](LICENSE).

package/RELEASING.md

@@ -0,0 +1,69 @@
+# Releasing
+
+Use **Actions > Release > Run workflow** on `master`. A dispatch requests a real release; there is no dry-run input. Opening or merging the workflow setup PR does not authorize publication. Finish the one-time setup and review the candidate before dispatching.
+
+## One-time Setup
+
+The package is initially unpublished. npm requires an existing package before its trusted publisher can be configured, unlike RubyGems pending publishers. The approved bootstrap uses npm staged publishing: stage a separate `0.0.1-bootstrap` candidate to establish the public `0.0.0-stage` placeholder on npm, then configure the trusted publisher and run the normal workflow for the real `0.1.0` release. This keeps changelog, tag, GitHub Release, and next-version preparation in release-it rather than creating bootstrap metadata PRs.
+
+Use npm 11.15.0 or later for staging and trusted-publisher configuration, with a compatible Node version. Log in and complete account-level 2FA locally; never share credentials. Prepare the bootstrap tarball from an isolated copy with version `0.0.1-bootstrap`, leaving tracked package and lockfile versions at `0.1.0`, then stage it:
+
+```sh
+npm stage publish .release/eslint-plugin-markdown-preferences-paragraph-0.0.1-bootstrap.tgz --access public --tag bootstrap
+```
+
+Keep the bootstrap stage pending until the real `0.1.0` release succeeds. Do not stage `0.1.0`: staged and published versions share the same unique version index. Do not approve the bootstrap candidate or reject it before the real release exists; rejecting the only stage can remove the placeholder and trigger the 24-hour npm unpublish lock.
+
+Create an npm trusted publisher at **Package > Settings > Trusted Publisher** with owner `dblock`, repository `eslint-plugin-markdown-preferences-paragraph`, workflow filename `release.yml`, and environment `release`. Explicitly allow direct `npm publish`, not only staged publication; staged approval requires a human and is not this workflow. Create the connection just before its first automated release: a new connection expires if its first successful publish does not happen within two days.
+
+The GitHub `release` environment is configured for only `master`, without required reviewers. Writers can dispatch releases; add maintainer reviewers if approval before publication is desired. The approved no-App setup removes the default branch's PR requirement, allowing all writers to push directly, while preserving active force-push and deletion protections without bypass actors. Ordinary development must still use PRs.
+
+After verifying the real release, reject the pending bootstrap stage with `npm stage reject <stage-id>`. Do not unpublish the public placeholder or the released package.
+
+The workflow uses Node 26.13.0 and requires npm 11.5.1 or later. It uses the built-in `GITHUB_TOKEN` for Git and GitHub Releases, with `contents: write` and `id-token: write`. No GitHub App, stored npm token, or `NODE_AUTH_TOKEN` is needed. npm automatically supplies provenance for this public package and repository.
+
+After verifying trusted publication, select **Require two-factor authentication and disallow tokens** in npm publishing-access settings. This does not disable OIDC. Never put registry credentials into the repository or this conversation.
+
+## Prepare and Dispatch
+
+Keep `package.json`, `package-lock.json`, and `## <version> (Next)` synchronized. Feature PRs choose their version according to the contributor policy; the workflow defaults to that checked-in version and automatically prepares the next patch after release. Require actual changelog entries, not just `- Your contribution here.`.
+
+Run local validation and confirm the separate Test, Lint, and Package checks before requesting publication:
+
+```sh
+npm ci
+npm run test:coverage
+npm run lint
+```
+
+The coverage command includes real packed-package CLI consumers; do not immediately repeat `package:check`. Release-tool tests use isolated Git repositories and simulated npm responses, never actual publication.
+
+After explicit release authorization, dispatch from `master`:
+
+```sh
+gh workflow run release.yml --repo github.com/dblock/eslint-plugin-markdown-preferences-paragraph --ref master
+```
+
+To override the checked-in version, provide a stable version without a `v` prefix:
+
+```sh
+gh workflow run release.yml --repo github.com/dblock/eslint-plugin-markdown-preferences-paragraph --ref master -f version=0.2.0
+```
+
+Overrides cannot be older than the checked-in version. Prerelease versions are not supported. Concurrent release runs are serialized, and source changes after dispatch cause failure rather than rebasing or overwriting another writer.
+
+## Automated Sequence
+
+Actions checks out the exact dispatched commit and runs only on `master` in the restricted release environment, using the pinned Node runtime. Hooks require a clean installation, meaningful release notes, an unpublished version, and an absent tag. Release-it updates version declarations; hooks date the Next section in UTC, remove its placeholder while preserving prior entries, and update the README npm installation pin to the release version before packing.
+
+The hooks pack once to `.release/package.tgz`, retain a checksum and metadata patch, run lint, and pass that exact archive to the full tests through `PARAGRAPH_WRAP_PACKAGE_ARCHIVE`. The real consumer suite inspects and installs it, checks version and logo integrity, and exercises ESLint check/fix/stability fixtures. Release changes are limited to package version fields, the changelog, and README. Immediately before publication, hooks reject changed metadata/artifacts or an advanced remote `master`.
+
+Release-it's native npm publisher publishes that retained tarball through OIDC, without repacking. Its native Git plugin then commits the metadata, creates the annotated tag, and atomically pushes the commit/tag. Before creating the GitHub Release, a hook verifies that the remote branch/tag match the release commit and that the registry version/integrity match the validated archive. Release-it attaches the tarball/checksum to the GitHub Release.
+
+After publication and GitHub Release creation succeed, a second release-it run increments patch, creates the new Next section and placeholder through its changelog hook, runs lint and full tests for that next version, and commits/pushes its metadata. The README installation pin stays at the released version, not the unpublished development version. This run does not publish, create tags, or create another GitHub Release. No ordinary development commits are authorized to bypass PRs.
+
+## Failure Recovery
+
+Download the run's release artifacts before retention expires: the tarball, checksum, and release metadata patch are retained for 14 days even when later stages fail. Do not blindly rerun a failed release; its tag or npm version may already exist, and the workflow deliberately rejects duplicates. Native destructive rollback handlers are disabled; prepared metadata is not reset on failure.
+
+Check the remote tag/commit, npm version and `dist.integrity`, GitHub Release, and current `master` before choosing recovery. npm is published before Git is pushed: if Git fails after successful publication, reconstruct the release metadata from the exact dispatched source and retained patch, reconcile any newer work without overwriting it, and finish the missing commit/tag push only with explicit authorization. If npm publication failed, investigate authentication and use the original validated tarball through an explicitly authorized workflow or interactive publication. Registry visibility can lag; verify it before treating a missing lookup as a failed publication. If only the GitHub Release or next-version preparation failed, finish those missing steps. Never overwrite registry versions, force-push `master`, delete release tags, unpublish, or reset another writer's work.

package/assets/logo.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" role="img" aria-labelledby="title description">
+  <title id="title">Paragraph Wrapping</title>
+  <desc id="description">A pale blue notepad with a thin border, muted blue paragraph lines, and a returning wrap arrow.</desc>
+  <path d="M60 20h108l40 40v156a20 20 0 0 1-20 20H60a20 20 0 0 1-20-20V40a20 20 0 0 1 20-20Z" fill="#f1f7fc" stroke="#b8cedf" stroke-width="2" stroke-linejoin="round"/>
+  <path d="M168 20v40h40Z" fill="#deebf6" stroke="#b8cedf" stroke-width="2" stroke-linejoin="round"/>
+  <g fill="none" stroke="#8cafca" stroke-width="6" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M72 76h70M72 106h110M72 136h60M72 166h60M72 196h110"/>
+    <path d="M174 128h8a18 18 0 0 1 0 36h-22"/>
+    <path d="m174 150-14 14 14 14"/>
+  </g>
+</svg>

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "eslint-plugin-markdown-preferences-paragraph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An ESLint plugin for checking and safely fixing Markdown paragraph wrapping.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "assets/logo.svg",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "DESIGN.md",
+    "RELEASING.md"
+  ],
+  "engines": {
+    "node": "^22.13.0 || >=24.0.0"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:coverage": "c8 --reporter=text --reporter=lcov npm test",
+    "lint": "npm run lint:code && npm run lint:markdown && npm run lint:workflows",
+    "lint:code": "eslint .",
+    "lint:markdown": "eslint --config eslint.config-markdown.js \"*.md\"",
+    "lint:workflows": "node scripts/check-workflow-names.js",
+    "release": "node scripts/release.js",
+    "package:check": "node --test test/integration.test.js"
+  },
+  "dependencies": {
+    "string-width": "^8.3.0"
+  },
+  "peerDependencies": {
+    "@eslint/markdown": "^8.0.0",
+    "eslint": "^9.39.0 || ^10.0.0"
+  },
+  "overrides": {
+    "get-uri": {
+      "basic-ftp": "^6.2.6"
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@eslint/markdown": "^8.0.3",
+    "@cspell/dict-software-terms": "^5.4.9",
+    "c8": "^12.0.0",
+    "eslint": "^10.14.0",
+    "eslint-plugin-markdown-preferences": "^0.43.0",
+    "cspell-lib": "^10.4.1",
+    "release-it": "^21.1.2",
+    "title-case": "^4.3.2",
+    "yaml": "^2.9.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph/issues"
+  },
+  "homepage": "https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph#readme",
+  "license": "MIT",
+  "author": "dblock",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "markdown",
+    "paragraph",
+    "wrap"
+  ],
+  "c8": {
+    "include": [
+      "src/**/*.js",
+      "scripts/**/*.js"
+    ]
+  }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+import wrap from "./rules/wrap.js";
+
+const { name, version } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+
+export default {
+  meta: { name, version },
+  rules: { wrap },
+};

package/src/rules/wrap.js

@@ -0,0 +1,355 @@
+import markdown from "@eslint/markdown";
+import stringWidth from "string-width";
+
+const containers = new Set([
+  "root", "list", "listItem", "blockquote", "footnoteDefinition",
+]);
+const literals = new Set([
+  "inlineCode", "inlineMath", "html", "link", "image",
+  "linkReference", "imageReference",
+]);
+
+function textWidth(text) {
+  return text.split("\t").reduce(
+    (width, part, index) =>
+      width + (index ? 4 - (width % 4) : 0) + stringWidth(part),
+    0,
+  );
+}
+
+function sourceLines(text) {
+  const lines = [];
+  for (const match of text.matchAll(/([^\r\n]*)(\r\n|\r|\n|$)/gu)) {
+    if (!match[0]) continue;
+    lines.push({
+      content: match[1],
+      ending: match[2],
+      start: match.index,
+      end: match.index + match[1].length,
+      number: lines.length + 1,
+    });
+  }
+  return lines;
+}
+
+function visit(node, callback, ancestors = []) {
+  callback(node, ancestors);
+  for (const child of node.children ?? []) {
+    visit(child, callback, [...ancestors, node]);
+  }
+}
+
+function normalized(ast) {
+  return JSON.stringify(ast, (key, value) => {
+    if (key === "position") return undefined;
+    if (value?.type === "text") {
+      return {
+        ...value,
+        value: value.value.replace(/[ \t]*(?:\r\n|\r|\n)[ \t]*/gu, " "),
+      };
+    }
+    return value;
+  });
+}
+
+function verifier(sourceCode, languageOptions) {
+  let languages;
+  const original = normalized(sourceCode.ast);
+  function parse(language, text) {
+    const result = language.parse({ body: text }, { languageOptions });
+    return result.ok ? normalized(result.ast) : null;
+  }
+  return (range, replacement) => {
+    // Rule contexts do not expose the active language. Require every matching
+    // public dialect to preserve the original AST, rather than guessing one.
+    languages ??= Object.values(markdown.languages).filter(
+      (language) => parse(language, sourceCode.text) === original,
+    );
+    const candidate =
+      sourceCode.text.slice(0, range[0]) +
+      replacement +
+      sourceCode.text.slice(range[1]);
+    return languages.length > 0 &&
+      languages.every((language) => parse(language, candidate) === original);
+  };
+}
+
+function continuationPrefix(prefix, ancestors) {
+  if (prefix.includes("\t")) return null;
+  let remaining = prefix;
+  let result = "";
+  let quotes = 0;
+  while (remaining) {
+    const match = remaining.match(
+      /^( +|> ?|(?:[-+*]|\d{1,9}[.)]) +|\[\^[^\]\r\n]+\]: *|\[[ xX]\] +)/u,
+    );
+    if (!match) return null;
+    const token = match[0];
+    if (token.startsWith(">")) {
+      quotes++;
+      result += token;
+    } else if (/^ +$/u.test(token)) {
+      result += token;
+    } else if (token.startsWith("[^")) {
+      if (!ancestors.some((node) => node.type === "footnoteDefinition")) return null;
+      result += "    ";
+    } else if (token.startsWith("[")) {
+      if (!ancestors.some((node) =>
+        node.type === "listItem" && typeof node.checked === "boolean"
+      )) return null;
+    } else {
+      if (!ancestors.some((node) => node.type === "listItem")) return null;
+      result += " ".repeat(token.length);
+    }
+    remaining = remaining.slice(token.length);
+  }
+  return quotes === ancestors.filter((node) => node.type === "blockquote").length
+    ? result
+    : null;
+}
+
+function continuationStart(line, quotes) {
+  let offset = 0;
+  for (let index = 0; index < quotes; index++) {
+    const match = line.slice(offset).match(/^[ \t]*> ?/u);
+    if (!match) break;
+    offset += match[0].length;
+  }
+  return offset + line.slice(offset).match(/^[ \t]*/u)[0].length;
+}
+
+function paragraphSegments(node, ancestors, lines, text) {
+  const quotes = ancestors.filter((parent) => parent.type === "blockquote").length;
+  const rows = lines
+    .slice(node.position.start.line - 1, node.position.end.line)
+    .map((line, index, selected) => {
+      const start = index === 0
+        ? node.position.start.offset
+        : line.start + continuationStart(line.content, quotes);
+      const end = index === selected.length - 1
+        ? node.position.end.offset
+        : line.end;
+      return {
+        ...line,
+        bodyStart: start,
+        bodyEnd: end,
+        prefix: text.slice(line.start, start),
+        body: text.slice(start, end),
+      };
+    });
+  const boundaries = new Set();
+  visit(node, (child) => {
+    if (child.type === "break") {
+      boundaries.add(child.position.start.line);
+    }
+    if (child.type === "html" && /^<br\s*\/?>$/iu.test(child.value)) {
+      const row = rows.find((line) => line.number === child.position.start.line);
+      if (!row) return;
+      if (/^[ \t]*$/u.test(text.slice(child.position.end.offset, row.bodyEnd))) {
+        boundaries.add(row.number);
+      }
+      if (/^[ \t]*$/u.test(text.slice(row.bodyStart, child.position.start.offset))) {
+        boundaries.add(row.number - 1);
+      }
+    }
+  });
+  const segments = [];
+  let segment = [];
+  for (const row of rows) {
+    segment.push(row);
+    if (boundaries.has(row.number)) {
+      segments.push(segment);
+      segment = [];
+    }
+  }
+  if (segment.length) segments.push(segment);
+  return segments;
+}
+
+function joinSegment(rows, node) {
+  const textNodes = node.children.filter((child) => child.type === "text");
+  const atoms = node.children.filter((child) => child.type !== "text");
+  let text = "";
+  const gaps = [];
+  for (const [index, row] of rows.entries()) {
+    if (index > 0) {
+      const boundary = rows[index - 1].end;
+      if (!atoms.some((atom) =>
+        atom.position.start.offset <= boundary &&
+        atom.position.end.offset > boundary
+      )) {
+        gaps.push({ start: text.length, end: text.length + 1 });
+      }
+      text += " ";
+    }
+    const body = index < rows.length - 1
+      ? row.body.replace(/[ \t]+$/u, "")
+      : row.body;
+    for (const match of body.matchAll(/[ \t]+/gu)) {
+      const start = row.bodyStart + match.index;
+      const end = start + match[0].length;
+      const escaped = body.slice(0, match.index).match(/\\+$/u)?.[0].length ?? 0;
+      if (escaped % 2 === 0 && textNodes.some((child) =>
+        child.position.start.offset <= start && child.position.end.offset >= end
+      )) {
+        gaps.push({ start: text.length + match.index, end: text.length + match.index + match[0].length });
+      }
+    }
+    text += body;
+  }
+  return {
+    text,
+    gaps: gaps.filter((gap) => gap.start > 0 && gap.end < text.length),
+  };
+}
+
+function wrapSegment(joined, firstPrefix, nextPrefix, suffix, width, ending) {
+  const { text, gaps } = joined;
+  const output = [];
+  let start = 0;
+  let prefix = firstPrefix;
+  let current = "";
+  let separator = "";
+  for (const gap of [...gaps, { start: text.length, end: text.length }]) {
+    const token = text.slice(start, gap.start);
+    if (current && textWidth(prefix + current + separator + token) > width) {
+      if (textWidth(prefix + current) > width) return null;
+      output.push(current);
+      prefix = nextPrefix;
+      current = token;
+    } else {
+      current += separator + token;
+    }
+    separator = text.slice(gap.start, gap.end);
+    start = gap.end;
+  }
+  if (textWidth(prefix + current + suffix) > width) return null;
+  output.push(current);
+  return output.join(ending + nextPrefix);
+}
+
+function lineEnding(rows, lines) {
+  const endings = new Set(rows.slice(0, -1).map((row) => row.ending));
+  if (endings.size > 1) return null;
+  if (endings.size === 1) return [...endings][0];
+  if (rows[0].ending) return rows[0].ending;
+  const fileEndings = new Set(lines.map((line) => line.ending).filter(Boolean));
+  return fileEndings.size > 1 ? null : [...fileEndings][0] ?? "\n";
+}
+
+export default {
+  meta: {
+    type: "layout",
+    languages: ["markdown/*", "markdown-preferences/*"],
+    docs: {
+      description: "Wrap or unwrap Markdown paragraphs without changing their structure.",
+      url: "https://github.com/dblock/eslint-plugin-markdown-preferences-paragraph#configuration",
+    },
+    fixable: "whitespace",
+    schema: [{
+      type: "object",
+      properties: {
+        width: {
+          oneOf: [
+            { type: "integer", minimum: 1 },
+            { enum: ["nowrap", "ignore"] },
+          ],
+        },
+      },
+      additionalProperties: false,
+    }],
+    messages: {
+      nowrap: "Keep each soft-wrapped paragraph segment on one source line.",
+      width: "Source line width {{actual}} exceeds the maximum of {{width}}.",
+      reflow: "Reflow this paragraph segment to width {{width}}.",
+    },
+  },
+  create(context) {
+    const width = context.options[0]?.width ?? "ignore";
+    const sourceCode = context.sourceCode;
+    if (width === "ignore" || sourceCode.ast.type !== "root") return {};
+    const lines = sourceLines(sourceCode.text);
+    const parents = new WeakMap();
+    visit(sourceCode.ast, (node, ancestors) => parents.set(node, ancestors));
+    const verify = verifier(sourceCode, context.languageOptions);
+
+    return {
+      paragraph(node) {
+        const ancestors = parents.get(node);
+        const segments = paragraphSegments(node, ancestors, lines, sourceCode.text);
+        const firstLine = lines[node.position.start.line - 1];
+        const prefix = continuationPrefix(
+          sourceCode.text.slice(firstLine.start, node.position.start.offset),
+          ancestors,
+        );
+        let unsafe = prefix === null || ancestors.some((parent) => !containers.has(parent.type));
+        const unsafeRanges = [];
+        visit(node, (child) => {
+          if (
+            (literals.has(child.type) &&
+              child.position.start.line !== child.position.end.line) ||
+            (child.type === "html" && child.value.includes("<!--"))
+          ) {
+            unsafeRanges.push([child.position.start.offset, child.position.end.offset]);
+          }
+        });
+        if (segments.flat().some((row) => /^(?::::|<<<)(?:\s|$)/u.test(row.body))) {
+          unsafe = true;
+        }
+
+        for (const rows of segments) {
+          const violations = width === "nowrap"
+            ? (rows.length > 1 ? [rows[0]] : [])
+            : rows.filter((row) => textWidth(row.content) > width);
+          const reflow = violations.length === 0;
+          if (width === "nowrap" && reflow) continue;
+          const range = [rows[0].bodyStart, rows.at(-1).bodyEnd];
+          const ending = lineEnding(rows, lines);
+          let replacement = null;
+          if (
+            !unsafe && ending &&
+            !rows.some((row) => row.prefix.includes("\t")) &&
+            !unsafeRanges.some(([start, end]) => start < range[1] && end > range[0])
+          ) {
+            const joined = joinSegment(rows, node);
+            replacement = width === "nowrap"
+              ? joined.text
+              : wrapSegment(
+                joined,
+                rows[0].prefix,
+                prefix,
+                sourceCode.text.slice(rows.at(-1).bodyEnd, rows.at(-1).end),
+                width,
+                ending,
+              );
+            if (replacement !== null && (
+              replacement === sourceCode.text.slice(range[0], range[1]) ||
+              !verify(range, replacement)
+            )) replacement = null;
+          }
+          if (reflow) {
+            if (replacement === null) continue;
+            violations.push(rows[0]);
+          }
+          for (const [index, row] of violations.entries()) {
+            context.report({
+              node,
+              loc: {
+                start: {
+                  line: row.number,
+                  column: width === "nowrap" ? row.bodyStart - row.start + 1 : 1,
+                },
+                end: { line: row.number, column: row.content.length + 1 },
+              },
+              messageId: width === "nowrap" ? "nowrap" : reflow ? "reflow" : "width",
+              data: { actual: String(textWidth(row.content)), width: String(width) },
+              ...(index === 0 && replacement !== null ? {
+                fix: (fixer) => fixer.replaceTextRange(range, replacement),
+              } : {}),
+            });
+          }
+        }
+      },
+    };
+  },
+};