@tai-kun/vp-lint-plugins 0.0.0 → 0.0.1

package/src/rules/comment-utils.ts

@@ -0,0 +1,218 @@
+import type { Comment, SourceCode } from "vite-plus/lint/plugins";
+
+interface CommentLine {
+  column: number;
+  content: string;
+  end: number;
+  line: number;
+  start: number;
+}
+
+const SENTENCE_END = /[。．.!?！？]$/u;
+const TRAILING_CLOSERS = /[」』】）》）〕〉］｝"'”’]+$/u;
+const DIRECTIVE_PREFIXES = [
+  "#!",
+  "///",
+  "oxlint-",
+  "eslint-",
+  "prettier-",
+  "@ts-",
+  "@type",
+  "@see",
+  "@link",
+  "TODO",
+  "FIXME",
+  "NOTE",
+  "HACK",
+  "XXX",
+  "istanbul",
+  "c8 ",
+  "v8 ",
+  "#region",
+  "#endregion",
+  "biome-",
+  "deno-",
+];
+
+function isBlank(text: string): boolean {
+  return text.trim() === "";
+}
+
+function isDirective(text: string): boolean {
+  const value = text.trimStart();
+
+  return DIRECTIVE_PREFIXES.some((prefix) => value.indexOf(prefix) === 0);
+}
+
+function isLabelLine(text: string): boolean {
+  const value = text.trim();
+
+  return /^[^\s:：]{1,20}[:：]\s/u.test(value) || /[:：]$/u.test(value);
+}
+
+function isTag(text: string): boolean {
+  return /^@[A-Za-z]/u.test(text.trimStart());
+}
+
+function isListOrHeading(text: string): boolean {
+  return /^(?:[-*+]\s|\d+[.)]\s|#{1,6}\s|\|)/u.test(text.trimStart());
+}
+
+function isCodeLike(text: string): boolean {
+  const value = text.trimStart();
+
+  return (
+    /^(?:```|~~~|const |let |var |function |return |if \(|for \(|while \(|switch \(|class |import |export |type |interface |\{|\}|\$ |> |pnpm |npm |npx |node |git |mise |yarn |bun |deno |curl |cd |echo |sudo |https?:\/\/)/u.test(
+      value,
+    ) || /=>|;\s*$/u.test(value)
+  );
+}
+
+function isFence(text: string): boolean {
+  const value = text.trimStart();
+
+  return value.slice(0, 3) === "```" || value.slice(0, 3) === "~~~";
+}
+
+function isSentenceEnd(text: string): boolean {
+  const value = text.trimEnd().replace(TRAILING_CLOSERS, "");
+
+  return SENTENCE_END.test(value);
+}
+
+/**
+ * 散文として扱わない行かどうかを返します。
+ */
+function isSkippableProseLine(text: string): boolean {
+  const trimmed = text.trim();
+
+  if (trimmed === "" || isFence(trimmed)) {
+    return true;
+  }
+
+  return (
+    isDirective(trimmed) ||
+    isLabelLine(trimmed) ||
+    isTag(trimmed) ||
+    isListOrHeading(trimmed) ||
+    isCodeLike(trimmed)
+  );
+}
+
+function getBlockLineInfos(comment: Comment, sourceCode: SourceCode): (CommentLine | null)[] {
+  const raw = sourceCode.getText(comment);
+
+  if (!raw.includes("\n")) {
+    return [];
+  }
+
+  const lines = raw.split("\n");
+  const infos: (CommentLine | null)[] = [];
+  let offset = comment.range[0];
+
+  for (const [index, line] of lines.entries()) {
+    let contentStart: number;
+    let contentEnd = line.length;
+
+    if (index === 0) {
+      contentStart = raw.slice(0, 3) === "/**" ? 3 : 2;
+    } else {
+      const match = /^(?<prefix>\s*\*[ \t]?).*$/u.exec(line);
+
+      if (match === null) {
+        infos.push(null);
+        offset += line.length + 1;
+        continue;
+      }
+
+      contentStart = match.groups?.["prefix"]?.length ?? 0;
+      const closeIndex = line.indexOf("*/");
+
+      if (closeIndex !== -1) {
+        contentEnd = Math.max(contentStart, closeIndex);
+      }
+    }
+
+    infos.push({
+      end: offset + contentEnd,
+      line: comment.loc.start.line + index,
+      start: offset + contentStart,
+      column: index === 0 ? comment.loc.start.column + contentStart : contentStart,
+      content: line.slice(contentStart, contentEnd),
+    });
+    offset += line.length + 1;
+  }
+
+  return infos;
+}
+
+function getLineGroupInfos(group: readonly Comment[], sourceCode: SourceCode): CommentLine[] {
+  return group.map((comment) => {
+    const raw = sourceCode.getText(comment);
+    const commentPrefix = raw.slice(0, 2) === "//" ? 2 : 0;
+    const spacePrefix = raw[commentPrefix] === " " ? 1 : 0;
+    const contentStart = commentPrefix + spacePrefix;
+
+    return {
+      end: comment.range[1],
+      line: comment.loc.start.line,
+      start: comment.range[0] + contentStart,
+      column: comment.loc.start.column + contentStart,
+      content: raw.slice(contentStart),
+    };
+  });
+}
+
+function getSingleLineBlockInfo(comment: Comment, sourceCode: SourceCode): CommentLine {
+  const raw = sourceCode.getText(comment);
+  const prefixLength = raw.startsWith("/**") ? 3 : 2;
+  const closeIndex = raw.lastIndexOf("*/");
+  const contentEnd = closeIndex === -1 ? raw.length : closeIndex;
+
+  return {
+    end: comment.range[0] + contentEnd,
+    line: comment.loc.start.line,
+    start: comment.range[0] + prefixLength,
+    column: comment.loc.start.column + prefixLength,
+    content: raw.slice(prefixLength, contentEnd),
+  };
+}
+
+/**
+ * コメントの内容行を返します。
+ *
+ * ブロックコメントで `*` の付かない行がある場合は、その行を null として返します。
+ */
+function getCommentLineInfos(comment: Comment, sourceCode: SourceCode): (CommentLine | null)[] {
+  if (comment.type === "Line") {
+    return getLineGroupInfos([comment], sourceCode);
+  }
+
+  if (comment.type === "Shebang") {
+    return [];
+  }
+
+  const raw = sourceCode.getText(comment);
+
+  if (!raw.includes("\n")) {
+    return [getSingleLineBlockInfo(comment, sourceCode)];
+  }
+
+  return getBlockLineInfos(comment, sourceCode);
+}
+
+export type { CommentLine };
+
+export {
+  isTag,
+  isBlank,
+  isFence,
+  isCodeLike,
+  isDirective,
+  isLabelLine,
+  isSentenceEnd,
+  isListOrHeading,
+  getLineGroupInfos,
+  getCommentLineInfos,
+  isSkippableProseLine,
+};

package/src/rules/jsdoc-param-order.ts

@@ -0,0 +1,137 @@
+import { defineRule } from "vite-plus/lint/plugins";
+import type { ESTree, Context, SourceCode } from "vite-plus/lint/plugins";
+
+import { getNodeJSDoc, getParamName, getJSDocLines, hasExampleOrFence } from "./jsdoc-utils.js";
+
+function getParamNameFromPattern(param: ESTree.ParamPattern): string | null {
+  if (param.type === "Identifier") {
+    return param.name;
+  }
+
+  if (param.type === "AssignmentPattern") {
+    return param.left.type === "Identifier" ? param.left.name : null;
+  }
+
+  if (param.type === "RestElement") {
+    return param.argument.type === "Identifier" ? param.argument.name : null;
+  }
+
+  if (param.type === "TSParameterProperty") {
+    return getParamNameFromPattern(param.parameter);
+  }
+
+  return null;
+}
+
+function getExpectedParams(params: readonly ESTree.ParamPattern[]): string[] | null {
+  const names: string[] = [];
+
+  for (const param of params) {
+    const name = getParamNameFromPattern(param);
+
+    if (name === null) {
+      return null;
+    }
+
+    names.push(name);
+  }
+
+  return names;
+}
+
+function checkFunction(
+  context: Context,
+  sourceCode: SourceCode,
+  node: ESTree.Node,
+  params: readonly ESTree.ParamPattern[],
+): void {
+  const comment = getNodeJSDoc(node, sourceCode);
+
+  if (comment === null) {
+    return;
+  }
+
+  const lines = getJSDocLines(comment, sourceCode);
+
+  if (lines === null || hasExampleOrFence(lines)) {
+    return;
+  }
+
+  const tagNames = lines
+    .filter((line) => line.tagName === "param")
+    .map((line) => getParamName(line.content));
+
+  if (tagNames.length === 0 || tagNames.some((name) => name === null)) {
+    return;
+  }
+
+  const expected = getExpectedParams(params);
+
+  if (expected === null || expected.length !== tagNames.length) {
+    return;
+  }
+
+  if (
+    new Set(expected).size !== expected.length ||
+    new Set(tagNames).size !== tagNames.length ||
+    tagNames.some((name) => name?.includes(".") === true)
+  ) {
+    return;
+  }
+
+  for (const [index, name] of tagNames.entries()) {
+    if (name !== expected[index]) {
+      context.report({
+        loc: comment.loc,
+        messageId: "paramOrder",
+      });
+
+      return;
+    }
+  }
+}
+
+/**
+ * `@param` タグが関数の引数の順序に従っていることを要求します。
+ */
+const jsdocParamOrder = defineRule({
+  meta: {
+    docs: {
+      description: "Require @param tags to follow the order of function parameters.",
+    },
+    type: "suggestion",
+    messages: {
+      paramOrder: "@param tags must follow the order of function parameters.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      MethodDefinition(node): void {
+        checkFunction(context, sourceCode, node, node.value.params);
+      },
+      TSDeclareFunction(node): void {
+        checkFunction(context, sourceCode, node, node.params);
+      },
+      FunctionDeclaration(node): void {
+        checkFunction(context, sourceCode, node, node.params);
+      },
+      ExportNamedDeclaration(node): void {
+        const declaration = node.declaration;
+
+        if (
+          declaration !== null &&
+          (declaration.type === "FunctionDeclaration" || declaration.type === "TSDeclareFunction")
+        ) {
+          checkFunction(context, sourceCode, node, declaration.params);
+        }
+      },
+      TSAbstractMethodDefinition(node): void {
+        checkFunction(context, sourceCode, node, node.value.params);
+      },
+    };
+  },
+});
+
+export default jsdocParamOrder;

package/src/rules/jsdoc-tag-lines.ts

@@ -0,0 +1,165 @@
+import { defineRule } from "vite-plus/lint/plugins";
+
+import type { JSDocLine } from "./jsdoc-utils.js";
+import { getJSDocLines, hasExampleOrFence } from "./jsdoc-utils.js";
+
+interface Entry {
+  groupId: number;
+  line: JSDocLine;
+  lineIndex: number;
+}
+
+function getBlankPrefix(line: JSDocLine): string {
+  return line.prefix.trimEnd();
+}
+
+/**
+ * description とタグ、タググループの間の空行を揃えます。
+ */
+const jsdocTagLines = defineRule({
+  meta: {
+    docs: {
+      description: "Require consistent blank lines between JSDoc tag groups.",
+    },
+    type: "layout",
+    fixable: "whitespace",
+    messages: {
+      missingBlankLine: "Expected a blank line between JSDoc tag groups.",
+      unexpectedBlankLine: "Unexpected blank line in a JSDoc tag group.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      "Program:exit"(): void {
+        for (const comment of sourceCode.getAllComments()) {
+          if (comment.type !== "Block") {
+            continue;
+          }
+
+          const lines = getJSDocLines(comment, sourceCode);
+
+          if (lines === null || lines.length < 3 || hasExampleOrFence(lines)) {
+            continue;
+          }
+
+          const opening = lines[0];
+          const closing = lines.at(-1);
+
+          if (
+            opening === undefined ||
+            closing === undefined ||
+            opening.content.trim() !== "" ||
+            closing.content.trim() !== ""
+          ) {
+            continue;
+          }
+
+          const contentLines = lines.slice(1, -1);
+          const entries: Entry[] = [];
+
+          for (const [index, line] of contentLines.entries()) {
+            if (line.content.trim() !== "") {
+              entries.push({
+                line,
+                groupId: -1,
+                lineIndex: index,
+              });
+            }
+          }
+
+          if (entries.length === 0 || !entries.some((entry) => entry.line.tagName !== null)) {
+            continue;
+          }
+
+          let firstTagIndex = -1;
+          let currentGroup = -1;
+          let currentTag: string | null = null;
+
+          for (const [index, entry] of entries.entries()) {
+            if (entry.line.tagName === null) {
+              if (currentTag === null) {
+                continue;
+              }
+
+              entry.groupId = currentGroup;
+              continue;
+            }
+
+            if (firstTagIndex === -1) {
+              firstTagIndex = index;
+            }
+
+            if (currentTag === null || entry.line.tagName !== currentTag) {
+              currentGroup += 1;
+              currentTag = entry.line.tagName;
+            }
+
+            entry.groupId = currentGroup;
+          }
+
+          if (firstTagIndex === -1) {
+            continue;
+          }
+
+          const descriptionExists = firstTagIndex > 0;
+          const result: string[] = [opening.raw];
+          let previousEntry: Entry | null = null;
+          let missingBlankLine = false;
+
+          for (const entry of entries) {
+            let desiredBlankLines: number;
+            let originalBlankLines: number;
+
+            if (previousEntry === null) {
+              originalBlankLines = entry.lineIndex;
+              desiredBlankLines = 0;
+            } else {
+              originalBlankLines = entry.lineIndex - previousEntry.lineIndex - 1;
+
+              if (previousEntry.groupId === -1 && entry.groupId === -1) {
+                desiredBlankLines = originalBlankLines;
+              } else if (previousEntry.groupId === -1) {
+                desiredBlankLines = descriptionExists ? 1 : 0;
+              } else {
+                desiredBlankLines = previousEntry.groupId === entry.groupId ? 0 : 1;
+              }
+            }
+
+            if (desiredBlankLines > originalBlankLines) {
+              missingBlankLine = true;
+            }
+
+            const blankPrefix = getBlankPrefix(entry.line);
+
+            for (let count = 0; count < desiredBlankLines; count += 1) {
+              result.push(blankPrefix);
+            }
+
+            result.push(entry.line.raw);
+            previousEntry = entry;
+          }
+
+          result.push(closing.raw);
+
+          const replacement = result.join("\n");
+
+          if (replacement === sourceCode.getText(comment)) {
+            continue;
+          }
+
+          context.report({
+            fix(fixer) {
+              return fixer.replaceText(comment, replacement);
+            },
+            loc: comment.loc,
+            messageId: missingBlankLine ? "missingBlankLine" : "unexpectedBlankLine",
+          });
+        }
+      },
+    };
+  },
+});
+
+export default jsdocTagLines;

package/src/rules/jsdoc-tag-order.ts

@@ -0,0 +1,75 @@
+import { defineRule } from "vite-plus/lint/plugins";
+
+import { getJSDocLines, hasExampleOrFence } from "./jsdoc-utils.js";
+
+const TAG_ORDER: Record<string, number> = {
+  see: 70,
+  beta: 65,
+  note: 50,
+  param: 10,
+  throws: 40,
+  default: 20,
+  returns: 30,
+  internal: 65,
+  template: 5,
+  typeParam: 5,
+  deprecated: 60,
+};
+const UNKNOWN_TAG_ORDER = 100;
+
+/**
+ * JSDoc のタグの順序を統一します。
+ */
+const jsdocTagOrder = defineRule({
+  meta: {
+    docs: {
+      description: "Enforce a consistent order of JSDoc tags.",
+    },
+    type: "suggestion",
+    messages: {
+      order:
+        "JSDoc tags must be ordered as follows: @param, @default, @returns, @throws, @note, @deprecated, @see.",
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    return {
+      "Program:exit"(): void {
+        for (const comment of sourceCode.getAllComments()) {
+          if (comment.type !== "Block") {
+            continue;
+          }
+
+          const lines = getJSDocLines(comment, sourceCode);
+
+          if (lines === null || hasExampleOrFence(lines)) {
+            continue;
+          }
+
+          let previousOrder: number | null = null;
+
+          for (const line of lines) {
+            if (line.tagName === null) {
+              continue;
+            }
+
+            const order = TAG_ORDER[line.tagName] ?? UNKNOWN_TAG_ORDER;
+
+            if (previousOrder !== null && order < previousOrder) {
+              context.report({
+                loc: comment.loc,
+                messageId: "order",
+              });
+              break;
+            }
+
+            previousOrder = order;
+          }
+        }
+      },
+    };
+  },
+});
+
+export default jsdocTagOrder;