@aforemendude/prettier-plugin-wrap-comments 1.0.2 → 1.0.3

package/README.md

@@ -1,7 +1,12 @@
 # @aforemendude/prettier-plugin-wrap-comments
 
-A Prettier plugin that wraps non-JSDoc JavaScript and TypeScript comments as Markdown. It uses the comment marker's real
-column to calculate the available content width, so nested comments wrap more narrowly than top-level comments.
+A Prettier plugin that wraps non-JSDoc JavaScript and TypeScript comments as Markdown. It uses each comment marker's
+real column to calculate the available content width, so nested comments wrap more narrowly than top-level comments.
+
+## Requirements
+
+- Node.js 18 or newer
+- Prettier 3 or newer
 
 ## Install
 
@@ -27,8 +32,17 @@ npx prettier --write .
 
 ## Behavior
 
-The plugin wraps standalone `//` and `/* ... */` comments before Prettier parses the file, then delegates formatting to
-Prettier's built-in JavaScript and TypeScript parsers.
+The plugin wraps comments for Prettier's `babel`, `babel-ts`, and `typescript` parsers. It runs during parser
+preprocessing: the underlying Prettier parser preprocesses and parses the source first, the plugin rewrites eligible
+comments from that parsed comment list, and Prettier then formats the rewritten source with its built-in JavaScript and
+TypeScript printers. If the parser cannot parse the preprocessed source, the plugin leaves the source unchanged.
+
+Comment text is normalized and reflowed with Prettier's Markdown parser. The available content width is based on
+Prettier's `printWidth` minus the column where the comment text starts. `tabWidth`, `useTabs`, and `endOfLine` are used
+when measuring and rebuilding comments.
+
+Standalone `//` comments are wrapped in place. Adjacent standalone line comments are combined and reflowed as one
+Markdown block when they are directly next to each other and their `//` markers start in the same column.
 
 ```ts
 function example() {
@@ -38,18 +52,39 @@ function example() {
 }
 ```
 
-JSDoc comments are left unchanged:
+Trailing `//` comments stay in place when the full source line fits within `printWidth`. If the source line is too long,
+the comment is moved above the code and wrapped using the code line's indentation.
+
+```ts
+function example() {
+  // This trailing comment moved above the statement because the original line
+  // was too long.
+  const value = 1;
+}
+```
+
+Non-JSDoc `/* ... */` comments are also normalized as Markdown. A block comment may stay on one line if the normalized
+comment fits within `printWidth`; otherwise, only standalone block comments are expanded into star-prefixed blocks. Long
+inline block comments are left unchanged when they cannot fit on one line.
 
 ```ts
-/**
- * This documentation comment is not wrapped by the plugin.
- */
+if (ready) {
+  /*
+   * This block comment is wrapped with the nested indentation included in the
+   * available width calculation.
+   */
+  run();
+}
 ```
 
-Tooling directives such as `eslint-disable`, `@ts-expect-error`, `prettier-ignore`, source maps, and TypeScript
-triple-slash directives are also left untouched so their meaning is not changed. Trailing comments after code stay in
-place when the full line fits the configured print width. If the line is too long, the comment is moved above the code
-and wrapped there.
+The plugin leaves these comments unchanged:
+
+- JSDoc comments that start with `/**`
+- bang-preserved comments that start with `/*!` or `//!`
+- TypeScript-style triple-slash line comments that start with `///`
+- empty comment bodies
+- directive comments such as `@license`, `@preserve`, JSX and TypeScript pragmas, source map directives, `#__PURE__`,
+  `@__PURE__`, lint/coverage/formatter directives, `vite-ignore`, and webpack magic comments
 
 ## Supported Parsers
 
@@ -61,19 +96,9 @@ and wrapped there.
 
 ```sh
 npm install
-npm run check
-```
-
-## Publishing
-
-The npm package name is `@aforemendude/prettier-plugin-wrap-comments`.
-
-Before publishing, make sure the version in `package.json` has been updated, then run:
-
-```sh
-npm run check
-npm publish --access public
+npm run format:check
+npm run test
 ```
 
-The package scripts already run the important publish checks: `prepublishOnly` runs `npm run check`, and `prepack`
-builds the `dist` files that are included in the published package.
+`npm run test` builds `dist` before running the Node test suite. `npm run verify` runs `npm install`,
+`npm run format:check`, and `npm run test`.

package/dist/comments/block.js

@@ -1,10 +1,10 @@
-import { isDirectiveComment, normalizeBlockCommentBody } from './core.js';
+import { hasPreserveCommentMarker, isDirectiveComment, normalizeBlockCommentBody } from './core.js';
 import { formatMarkdownLines } from '../shared/markdown.js';
 import { getAvailableContentWidth, getPrintWidth, getTabWidth } from '../shared/options.js';
 import { getColumnAt, getColumns, getLinePrefix, getPreferredNewline, isStandaloneBlockComment, } from '../shared/text.js';
 export async function wrapBlockComment(text, comment, options) {
     const raw = text.slice(comment.start, comment.end);
-    if (raw.startsWith('/**')) {
+    if (raw.startsWith('/**') || hasPreserveCommentMarker(raw)) {
         return undefined;
     }
     const markdown = normalizeBlockCommentBody(raw);

package/dist/comments/core.d.ts

@@ -4,3 +4,4 @@ export declare function toCommentRange(comment: RawComment, text: string): Comme
 export declare function normalizeLineCommentBody(rawBody: string): string;
 export declare function normalizeBlockCommentBody(rawComment: string): string;
 export declare function isDirectiveComment(body: string): boolean;
+export declare function hasPreserveCommentMarker(rawComment: string): boolean;

package/dist/comments/core.js

@@ -63,8 +63,53 @@ export function normalizeBlockCommentBody(rawComment) {
     })
         .join('\n');
 }
+const PRAGMA_DIRECTIVE_COMMENT_PATTERNS = [
+    /^@(?:license|preserve)\b/u,
+    /^@(?:jsxFrag|jsxImportSource|jsxRuntime|jsx)\b/u,
+    /^@(?:ts-check|ts-expect-error|ts-ignore|ts-nocheck)\b/u,
+    /^[@#]__(?:NO_SIDE_EFFECTS|PURE)__\b/u,
+];
+const SOURCE_MAP_DIRECTIVE_COMMENT_PATTERNS = [
+    /^[#@][ \t]*sourceMappingURL=/u,
+    /^[#@][ \t]*sourceURL=/u,
+    /^sourceMappingURL=/u,
+    /^sourceURL=/u,
+];
+const TOOL_DIRECTIVE_COMMENT_PATTERNS = [
+    /^biome-ignore\b/u,
+    /^c8\b/u,
+    /^deno-lint-ignore\b/u,
+    /^eslint\b/u,
+    /^eslint-/u,
+    /^exported\b/u,
+    /^globals?\b/u,
+    /^istanbul\b/u,
+    /^jshint\b/u,
+    /^nyc\b/u,
+    /^oxlint\b/u,
+    /^prettier-ignore\b/u,
+    /^prettier-ignore-start\b/u,
+    /^prettier-ignore-end\b/u,
+    /^stylelint\b/u,
+    /^tslint\b/u,
+    /^v8\b/u,
+    /^vite-ignore\b/u,
+];
+const BUNDLER_DIRECTIVE_COMMENT_PATTERNS = [
+    /^webpack(?:ChunkName|Exclude|Ignore|Include|Mode|Prefetch|Preload)\b/u,
+];
+const DIRECTIVE_COMMENT_PATTERNS = [
+    ...PRAGMA_DIRECTIVE_COMMENT_PATTERNS,
+    ...SOURCE_MAP_DIRECTIVE_COMMENT_PATTERNS,
+    ...TOOL_DIRECTIVE_COMMENT_PATTERNS,
+    ...BUNDLER_DIRECTIVE_COMMENT_PATTERNS,
+];
 export function isDirectiveComment(body) {
-    return /^(?:@(?:__NO_SIDE_EFFECTS__|__PURE__|jsx|jsxImportSource|license|preserve|ts-check|ts-expect-error|ts-ignore|ts-nocheck)\b|#\s*sourceMappingURL=|[@#]__PURE__\b|biome-ignore\b|c8\b|deno-lint-ignore\b|eslint\b|eslint-|exported\b|globals?\b|istanbul\b|jshint\b|nyc\b|oxlint\b|prettier-ignore\b|prettier-ignore-start\b|prettier-ignore-end\b|sourceMappingURL=|stylelint\b|tslint\b|v8\b|vite-ignore\b|webpack(?:ChunkName|Exclude|Ignore|Include|Mode|Prefetch|Preload)\b)/u.test(body.trimStart());
+    const normalizedBody = body.trimStart();
+    return DIRECTIVE_COMMENT_PATTERNS.some((pattern) => pattern.test(normalizedBody));
+}
+export function hasPreserveCommentMarker(rawComment) {
+    return rawComment.startsWith('/*!') || rawComment.startsWith('//!');
 }
 function isBlankLine(line) {
     return line !== undefined && line.trim() === '';

package/dist/comments/line.js

@@ -1,4 +1,4 @@
-import { isDirectiveComment, normalizeLineCommentBody } from './core.js';
+import { hasPreserveCommentMarker, isDirectiveComment, normalizeLineCommentBody } from './core.js';
 import { formatMarkdownLines } from '../shared/markdown.js';
 import { getAvailableContentWidth, getPrintWidth, getTabWidth } from '../shared/options.js';
 import { getColumnAt, getColumns, getContinuationIndent, getLineEnd, getLinePrefix, getLineStart, getPreferredNewline, } from '../shared/text.js';
@@ -67,7 +67,7 @@ export async function wrapTrailingLineComment(text, comment, options) {
 }
 export function shouldSkipLineComment(text, comment) {
     const raw = text.slice(comment.start, comment.end);
-    if (raw.startsWith('///')) {
+    if (raw.startsWith('///') || hasPreserveCommentMarker(raw)) {
         return true;
     }
     return isDirectiveComment(normalizeLineCommentBody(raw.slice(2)));

package/dist/shared/text.js

@@ -1,11 +1,23 @@
 import { getTabWidth } from './options.js';
 export function applyReplacements(text, replacements) {
     let result = text;
-    for (const replacement of [...replacements].sort((left, right) => right.start - left.start)) {
+    for (const replacement of getNonOverlappingReplacements(replacements).sort((left, right) => right.start - left.start)) {
         result = result.slice(0, replacement.start) + replacement.text + result.slice(replacement.end);
     }
     return result;
 }
+function getNonOverlappingReplacements(replacements) {
+    return [...replacements]
+        .sort((left, right) => left.start - right.start || right.end - left.end)
+        .reduce((accepted, replacement) => {
+        const previous = accepted.at(-1);
+        if (previous === undefined || previous.end <= replacement.start) {
+            accepted.push(replacement);
+            return accepted;
+        }
+        return accepted;
+    }, []);
+}
 export function getPreferredNewline(text, options) {
     if (options.endOfLine === 'crlf') {
         return '\r\n';

package/package.json

@@ -51,5 +51,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.0.2"
+  "version": "1.0.3"
 }