|
| 1 | +import { bannedProseWords } from "../lib/banned-words.js"; |
| 2 | + |
| 3 | +function annotationEnd(text, start) { |
| 4 | + let cursor = start; |
| 5 | + while (/\s/.test(text[cursor] ?? "") && cursor < text.length) { |
| 6 | + cursor++; |
| 7 | + } |
| 8 | + if (text[cursor] !== "{") { |
| 9 | + return start; |
| 10 | + } |
| 11 | + let depth = 0; |
| 12 | + let quote; |
| 13 | + for (; cursor < text.length; cursor++) { |
| 14 | + const character = text[cursor]; |
| 15 | + if (quote) { |
| 16 | + if (character === "\\") { |
| 17 | + cursor++; |
| 18 | + } else if (character === quote) { |
| 19 | + quote = undefined; |
| 20 | + } |
| 21 | + } else if (character === '"' || character === "'" || character === "`") { |
| 22 | + quote = character; |
| 23 | + } else if (character === "{") { |
| 24 | + depth++; |
| 25 | + } else if (character === "}") { |
| 26 | + if (--depth === 0) { |
| 27 | + return cursor + 1; |
| 28 | + } |
| 29 | + } |
| 30 | + } |
| 31 | + return start; |
| 32 | +} |
| 33 | + |
| 34 | +function prose(comment) { |
| 35 | + const characters = []; |
| 36 | + const offsets = []; |
| 37 | + const body = comment.value.slice(1); |
| 38 | + let offset = comment.range[0] + 3; |
| 39 | + |
| 40 | + for (const line of body.matchAll(/[^\n]*(?:\n|$)/g)) { |
| 41 | + const margin = /^\s*\* ?/.exec(line[0])?.[0].length ?? 0; |
| 42 | + for (let index = margin; index < line[0].length; index++) { |
| 43 | + characters.push(line[0][index]); |
| 44 | + offsets.push(offset + index); |
| 45 | + } |
| 46 | + offset += line[0].length; |
| 47 | + } |
| 48 | + |
| 49 | + // Annotation syntax and link targets name code; their descriptions remain prose. |
| 50 | + let text = characters.join(""); |
| 51 | + text = text.replace(/\{@(?:link|linkcode|linkplain)\s+[^\s|}]+/g, (value) => |
| 52 | + " ".repeat(value.length), |
| 53 | + ); |
| 54 | + text = text.replace(/^[ \t]*@example\b[^]*?(?=^[ \t]*@[\w-]+|$(?![^]))/gm, (value) => |
| 55 | + value.replace(/[^\r\n]/g, " "), |
| 56 | + ); |
| 57 | + const original = text; |
| 58 | + for (const tag of original.matchAll(/^[ \t]*@([\w-]+)/gm)) { |
| 59 | + let end = annotationEnd(original, tag.index + tag[0].length); |
| 60 | + if ( |
| 61 | + /^(?:param|arg|argument|property|prop|typedef|callback|template|typeParam|extends|implements|see)$/.test( |
| 62 | + tag[1], |
| 63 | + ) |
| 64 | + ) { |
| 65 | + const name = /^[ \t]+(?:\[[^\]\n]*\]|[\w.$]+(?:[ \t]*,[ \t]*[\w.$]+)*)/.exec( |
| 66 | + original.slice(end), |
| 67 | + ); |
| 68 | + end += name?.[0].length ?? 0; |
| 69 | + } |
| 70 | + text = |
| 71 | + text.slice(0, tag.index) + |
| 72 | + text.slice(tag.index, end).replace(/[^\r\n]/g, " ") + |
| 73 | + text.slice(end); |
| 74 | + } |
| 75 | + return { text, offsets }; |
| 76 | +} |
| 77 | + |
| 78 | +export const noBannedJsdocWords = { |
| 79 | + meta: { |
| 80 | + type: "suggestion", |
| 81 | + messages: { |
| 82 | + forbidden: |
| 83 | + 'Avoid "{{word}}" in prose; choose wording for its meaning (scripts/banned-words.js).', |
| 84 | + }, |
| 85 | + }, |
| 86 | + create(context) { |
| 87 | + const source = context.sourceCode; |
| 88 | + return { |
| 89 | + Program() { |
| 90 | + for (const comment of source.getAllComments()) { |
| 91 | + if (comment.type !== "Block" || !source.text.startsWith("/**", comment.range[0])) { |
| 92 | + continue; |
| 93 | + } |
| 94 | + const { text, offsets } = prose(comment); |
| 95 | + for (const { word, offset } of bannedProseWords(text)) { |
| 96 | + const start = offsets[offset]; |
| 97 | + context.report({ |
| 98 | + loc: { |
| 99 | + start: source.getLocFromIndex(start), |
| 100 | + end: source.getLocFromIndex(start + word.length), |
| 101 | + }, |
| 102 | + messageId: "forbidden", |
| 103 | + data: { word }, |
| 104 | + }); |
| 105 | + } |
| 106 | + } |
| 107 | + }, |
| 108 | + }; |
| 109 | + }, |
| 110 | +}; |
0 commit comments