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

package/src/rules/jsdoc-utils.ts

@@ -0,0 +1,179 @@
+import type { ESTree, Comment, SourceCode } from "vite-plus/lint/plugins";
+
+import { isFence } from "./comment-utils.js";
+
+interface JSDocLine {
+  content: string;
+  prefix: string;
+  raw: string;
+  tagName: string | null;
+}
+
+function getTagName(text: string): string | null {
+  const match = /^@(?<tag>[A-Za-z][\w-]*)/u.exec(text.trimStart());
+
+  return match?.groups?.["tag"] ?? null;
+}
+
+function stripType(value: string): string {
+  if (!value.startsWith("{")) {
+    return value;
+  }
+
+  let depth = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+
+    if (character === "{") {
+      depth += 1;
+    } else if (character === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return value.slice(index + 1).trimStart();
+      }
+    }
+  }
+
+  return value;
+}
+
+/**
+ * `@param` 行からパラメーター名を取得します。
+ */
+function getParamName(content: string): string | null {
+  let value = content.trimStart();
+
+  if (getTagName(value) !== "param") {
+    return null;
+  }
+
+  value = stripType(value.slice("@param".length).trimStart());
+
+  const match = /^(?<name>\S+)/u.exec(value);
+  const name = match?.groups?.["name"] ?? null;
+
+  if (name === null) {
+    return null;
+  }
+
+  return name
+    .replace(/^\[/u, "")
+    .replace(/\]$/u, "")
+    .replace(/^\.\.\./u, "")
+    .replace(/=.*$/u, "");
+}
+
+/**
+ * JSDoc コメントの各行を返します。
+ *
+ * JSDoc でない場合や、`*` の付かない行がある場合は null を返します。
+ */
+function getJSDocLines(comment: Comment, sourceCode: SourceCode): JSDocLine[] | null {
+  const raw = sourceCode.getText(comment);
+
+  if (!raw.startsWith("/**") || comment.type !== "Block") {
+    return null;
+  }
+
+  const rawLines = raw.split("\n");
+
+  if (rawLines.length === 1) {
+    const contentStart = 3;
+    const contentEnd = raw.lastIndexOf("*/");
+    const content = raw.slice(contentStart, contentEnd);
+
+    return [
+      {
+        raw,
+        prefix: raw.slice(0, contentStart),
+        content,
+        tagName: getTagName(content),
+      },
+    ];
+  }
+
+  const lines: JSDocLine[] = [];
+
+  for (const [index, line] of rawLines.entries()) {
+    if (index === 0) {
+      const contentStart = 3;
+      const closeIndex = line.lastIndexOf("*/");
+      const contentEnd = closeIndex === -1 ? line.length : Math.max(contentStart, closeIndex);
+      const content = line.slice(contentStart, contentEnd);
+
+      lines.push({
+        raw: line,
+        prefix: line.slice(0, contentStart),
+        content,
+        tagName: getTagName(content),
+      });
+      continue;
+    }
+
+    const match = /^(?<prefix>\s*\*[ \t]?).*$/u.exec(line);
+
+    if (match === null) {
+      return null;
+    }
+
+    const prefix = match.groups?.["prefix"] ?? "";
+    const contentStart = prefix.length;
+    const closeIndex = line.lastIndexOf("*/");
+    const contentEnd = closeIndex === -1 ? line.length : Math.max(contentStart, closeIndex);
+    const content = line.slice(contentStart, contentEnd);
+
+    lines.push({
+      raw: line,
+      prefix,
+      content,
+      tagName: getTagName(content),
+    });
+  }
+
+  return lines;
+}
+
+function hasExampleOrFence(lines: readonly JSDocLine[]): boolean {
+  return lines.some((line) => line.tagName === "example" || isFence(line.content));
+}
+
+function getNodeStart(node: ESTree.Node): number {
+  if ("decorators" in node) {
+    const decorator = node.decorators?.[0];
+
+    if (decorator !== undefined) {
+      return decorator.range[0];
+    }
+  }
+
+  return node.range[0];
+}
+
+/**
+ * ノードに付いている JSDoc コメントを返します。
+ */
+function getNodeJSDoc(node: ESTree.Node, sourceCode: SourceCode): Comment | null {
+  const start = getNodeStart(node);
+  const comment = sourceCode.getAllComments().findLast((candidate) => candidate.range[1] <= start);
+
+  if (comment === null || comment === undefined || comment.type !== "Block") {
+    return null;
+  }
+
+  if (!sourceCode.getText(comment).startsWith("/**")) {
+    return null;
+  }
+
+  if (sourceCode.text.slice(comment.range[1], start).trim() !== "") {
+    return null;
+  }
+
+  const startLine = sourceCode.getLocFromIndex(start).line;
+
+  return comment.loc.end.line === startLine - 1 ? comment : null;
+}
+
+export type { JSDocLine };
+
+export { getTagName, getNodeJSDoc, getParamName, getJSDocLines, hasExampleOrFence };

package/src/rules/member-ordering.ts

@@ -0,0 +1,93 @@
+import { defineRule } from "vite-plus/lint/plugins";
+import type { ESTree } from "vite-plus/lint/plugins";
+
+type MemberGroup =
+  | "static-field"
+  | "static-block"
+  | "instance-field"
+  | "constructor"
+  | "static-method"
+  | "instance-method";
+
+const MEMBER_GROUP_ORDER: Record<MemberGroup, number> = {
+  constructor: 3,
+  "static-block": 1,
+  "static-field": 0,
+  "static-method": 4,
+  "instance-field": 2,
+  "instance-method": 5,
+};
+
+function getMemberGroup(member: ESTree.ClassElement): MemberGroup | null {
+  if (member.type === "StaticBlock") {
+    return "static-block";
+  }
+
+  if (member.type === "TSIndexSignature") {
+    return null;
+  }
+
+  if (
+    member.type === "PropertyDefinition" ||
+    member.type === "TSAbstractPropertyDefinition" ||
+    member.type === "AccessorProperty" ||
+    member.type === "TSAbstractAccessorProperty"
+  ) {
+    return member.static ? "static-field" : "instance-field";
+  }
+
+  if (member.type === "MethodDefinition" || member.type === "TSAbstractMethodDefinition") {
+    if (member.kind === "constructor") {
+      return "constructor";
+    }
+
+    return member.static ? "static-method" : "instance-method";
+  }
+
+  return null;
+}
+
+/**
+ * クラスメンバーを「static フィールド → static ブロック → インスタンスフィールド → constructor → static メソッド → インスタンスメソッド」の順に要求します。
+ */
+const memberOrdering = defineRule({
+  meta: {
+    docs: {
+      description:
+        "Require class members to be ordered as static fields, static blocks, instance fields, constructor, static methods, and instance methods.",
+    },
+    type: "suggestion",
+    messages: {
+      order:
+        "Class members must be ordered as static fields, static blocks, instance fields, constructor, static methods, and instance methods.",
+    },
+  },
+  create(context) {
+    return {
+      ClassBody(node): void {
+        let previousRank: number | null = null;
+
+        for (const member of node.body) {
+          const group = getMemberGroup(member);
+
+          if (group === null) {
+            continue;
+          }
+
+          const rank = MEMBER_GROUP_ORDER[group];
+
+          if (previousRank !== null && rank < previousRank) {
+            context.report({
+              node: member,
+              messageId: "order",
+            });
+          }
+
+          previousRank = rank;
+        }
+      },
+    };
+  },
+});
+
+export default memberOrdering;

package/src/rules/object-properties-newline.ts

@@ -0,0 +1,54 @@
+import { defineRule } from "vite-plus/lint/plugins";
+
+import { getSortPlan } from "./object-sort-utils.js";
+
+/**
+ * プロパティーが 2 つ以上あるオブジェクトリテラルを複数行にします。
+ *
+ * Oxfmt の `objectWrap` には「プロパティー数で改行を強制する」オプションがないため、改行を挿入する最小限の fix を提供します。
+ * `objectWrap: "preserve"` と組み合わせることで、後続の Oxfmt がプロパティーごとの改行とインデントを整えます。
+ */
+const objectPropertiesNewline = defineRule({
+  meta: {
+    docs: {
+      description: "Enforce multiline object literals when they have two or more properties.",
+    },
+    type: "layout",
+    fixable: "whitespace",
+    messages: {
+      multiline: "Objects with 2 or more properties must be multiline.",
+    },
+  },
+  create(context) {
+    return {
+      ObjectExpression(node): void {
+        if (node.properties.length < 2) {
+          return;
+        }
+
+        // 並び替え可能なオブジェクトは sort-object-properties が複数行化も担当します。
+        if (getSortPlan(node, context.sourceCode) !== null) {
+          return;
+        }
+
+        // Oxfmt は `{` の直後に改行があるかどうかで複数行を維持するため、最初のプロパティーが `{` と同じ行にある場合だけを対象にします。
+        const firstProperty = node.properties[0];
+
+        if (firstProperty === undefined || firstProperty.loc.start.line !== node.loc.start.line) {
+          return;
+        }
+
+        context.report({
+          fix(fixer) {
+            // Oxfmt は `{` の直後の改行を複数行オブジェクトの目印にするため、ここでは改行を 1 つ挿入するだけで十分です。
+            return fixer.insertTextAfterRange([node.range[0], node.range[0] + 1], "\n");
+          },
+          node,
+          messageId: "multiline",
+        });
+      },
+    };
+  },
+});
+
+export default objectPropertiesNewline;

package/src/rules/object-sort-utils.ts

@@ -0,0 +1,339 @@
+import type { ESTree, Comment, SourceCode } from "vite-plus/lint/plugins";
+
+type SortableObject = ESTree.ObjectExpression | ESTree.ObjectPattern;
+
+type SortableProperty = SortableObject["properties"][number];
+
+interface SortPlanOptions {
+  /**
+   * 末尾の RestElement を許可するかどうかです。
+   */
+  allowRest?: boolean;
+
+  /**
+   * 1 行のオブジェクトを複数行に整形するかどうかです。
+   */
+  forceMultiline?: boolean;
+}
+
+interface SortUnit {
+  endLine: number;
+  name: string | null;
+  property: SortableProperty;
+  startLine: number;
+  text: string;
+}
+
+type NamedSortUnit = SortUnit & { name: string };
+
+type SortPlan =
+  | {
+      needsFix: false;
+      replacement: null;
+    }
+  | {
+      needsFix: true;
+      replacement: string;
+    };
+
+function getLineStarts(text: string): number[] {
+  const starts = [0];
+
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") {
+      starts.push(index + 1);
+    }
+  }
+
+  return starts;
+}
+
+function getLineIndent(text: string, lineStarts: readonly number[], line: number): string {
+  const start = lineStarts[line - 1] ?? 0;
+  const match = /^[ \t]*/u.exec(text.slice(start));
+
+  return match?.[0] ?? "";
+}
+
+function getPropertyName(property: SortableProperty): string | null {
+  if (property.type !== "Property" || property.computed || property.kind !== "init") {
+    return null;
+  }
+
+  const key = property.key;
+  let name: string;
+
+  if (key.type === "Identifier") {
+    name = key.name;
+  } else if (
+    key.type === "Literal" &&
+    (typeof key.value === "string" || typeof key.value === "number")
+  ) {
+    name = String(key.value);
+  } else {
+    return null;
+  }
+
+  return name === "__proto__" ? null : name;
+}
+
+function isSortableObject(node: SortableObject, allowRest: boolean): boolean {
+  if (node.properties.length < 2) {
+    return false;
+  }
+
+  const names = new Set<string>();
+
+  for (const [index, property] of node.properties.entries()) {
+    if (property.type === "RestElement") {
+      if (!allowRest || index !== node.properties.length - 1) {
+        return false;
+      }
+
+      continue;
+    }
+
+    const name = getPropertyName(property);
+
+    if (name === null || names.has(name)) {
+      return false;
+    }
+
+    names.add(name);
+  }
+
+  return true;
+}
+
+function compareNames(left: string, right: string): number {
+  if (left.length !== right.length) {
+    return left.length - right.length;
+  }
+
+  const leftLower = left.toLowerCase();
+  const rightLower = right.toLowerCase();
+
+  if (leftLower !== rightLower) {
+    return leftLower < rightLower ? -1 : 1;
+  }
+
+  if (left === right) {
+    return 0;
+  }
+
+  return left < right ? -1 : 1;
+}
+
+function compareUnits(left: NamedSortUnit, right: NamedSortUnit): number {
+  return compareNames(left.name, right.name);
+}
+
+function sortGroup(group: readonly SortUnit[]): SortUnit[] {
+  const sortable = group.filter((unit): unit is NamedSortUnit => unit.name !== null);
+
+  sortable.sort(compareUnits);
+  const rest = group.filter((unit) => unit.name === null);
+
+  return [...sortable, ...rest];
+}
+
+/**
+ * オブジェクトリテラル／オブジェクトパターンの並び替え計画を返します。
+ *
+ * - プロパティー名の長さが短い順、同じ長さなら名前順
+ * - 空行で区切られたグループ内だけで並び替え
+ * - プロパティー直上のコメントはプロパティーと一緒に移動
+ *
+ * 並び替えが安全でない場合は null を返します。
+ */
+function getSortPlan(
+  node: SortableObject,
+  sourceCode: SourceCode,
+  options: SortPlanOptions = {},
+): SortPlan | null {
+  const { allowRest = false, forceMultiline = true } = options;
+
+  if (!isSortableObject(node, allowRest)) {
+    return null;
+  }
+
+  const source = sourceCode.text;
+  const lineStarts = getLineStarts(source);
+  const lineIndent = getLineIndent(source, lineStarts, node.loc.start.line);
+  const comments = sourceCode
+    .getAllComments()
+    .filter((comment) => comment.range[0] >= node.range[0] && comment.range[1] <= node.range[1]);
+  const firstProperty = node.properties[0];
+
+  if (firstProperty === undefined) {
+    return null;
+  }
+
+  const inlineStart = firstProperty.loc.start.line === node.loc.start.line;
+  const singleLine = node.loc.start.line === node.loc.end.line;
+
+  const units: SortUnit[] = [];
+
+  if (inlineStart) {
+    if (comments.length > 0) {
+      return null;
+    }
+
+    for (const property of node.properties) {
+      const isRest = property.type === "RestElement";
+
+      units.push({
+        name: isRest ? null : getPropertyName(property),
+        text: source.slice(property.range[0], property.range[1]),
+        endLine: property.loc.end.line,
+        property,
+        startLine: property.loc.start.line,
+      });
+    }
+  } else {
+    let previousProperty: SortableProperty | null = null;
+
+    for (const property of node.properties) {
+      const previous = previousProperty;
+      const boundary = previous === null ? node.range[0] + 1 : previous.range[1];
+      const candidates = comments.filter(
+        (comment) => comment.range[0] >= boundary && comment.range[1] <= property.range[0],
+      );
+
+      if (
+        previous !== null &&
+        comments.some(
+          (comment) =>
+            comment.loc.start.line === previous.loc.end.line &&
+            comment.range[0] >= previous.range[1] &&
+            comment.range[1] <= property.range[0],
+        )
+      ) {
+        return null;
+      }
+
+      const attached: Comment[] = [];
+      let expectedLine = property.loc.start.line;
+
+      for (let index = candidates.length - 1; index >= 0; index -= 1) {
+        const comment = candidates[index];
+
+        if (comment === undefined) {
+          continue;
+        }
+
+        if (comment.loc.end.line !== expectedLine && comment.loc.end.line !== expectedLine - 1) {
+          return null;
+        }
+
+        if (comment.loc.start.line === expectedLine) {
+          return null;
+        }
+
+        if (comment.loc.start.line === node.loc.start.line) {
+          return null;
+        }
+
+        attached.unshift(comment);
+        expectedLine = comment.loc.start.line;
+      }
+
+      if (attached.length !== candidates.length) {
+        return null;
+      }
+
+      const first = attached[0] ?? property;
+      const startLine = first.loc.start.line;
+      const unitStart = lineStarts[startLine - 1] ?? 0;
+      const isRest = property.type === "RestElement";
+
+      units.push({
+        name: isRest ? null : getPropertyName(property),
+        text: source.slice(unitStart, property.range[1]),
+        endLine: property.loc.end.line,
+        property,
+        startLine,
+      });
+      previousProperty = property;
+    }
+
+    const lastProperty = node.properties.at(-1);
+
+    if (lastProperty === undefined) {
+      return null;
+    }
+
+    if (
+      comments.some(
+        (comment) =>
+          comment.range[0] >= lastProperty.range[1] && comment.range[1] <= node.range[1] - 1,
+      )
+    ) {
+      return null;
+    }
+  }
+
+  const groups: SortUnit[][] = [];
+  let currentGroup: SortUnit[] = [];
+  let previousEndLine: number | null = null;
+
+  for (const unit of units) {
+    if (previousEndLine !== null && unit.startLine > previousEndLine + 1) {
+      groups.push(currentGroup);
+      currentGroup = [];
+    }
+
+    currentGroup.push(unit);
+    previousEndLine = unit.endLine;
+  }
+
+  if (currentGroup.length > 0) {
+    groups.push(currentGroup);
+  }
+
+  let needsSort = false;
+
+  for (const group of groups) {
+    const sorted = sortGroup(group);
+
+    if (sorted.some((unit, index) => unit !== group[index])) {
+      needsSort = true;
+      break;
+    }
+  }
+
+  const needsFormat = forceMultiline && inlineStart;
+
+  if (!needsSort && !needsFormat) {
+    return {
+      needsFix: false,
+      replacement: null,
+    };
+  }
+
+  if (singleLine && !forceMultiline) {
+    const sortedUnits = sortGroup(units);
+
+    return {
+      needsFix: true,
+      replacement: `{ ${sortedUnits.map((unit) => unit.text).join(", ")} }`,
+    };
+  }
+
+  const groupsText = groups
+    .map((group) =>
+      sortGroup(group)
+        .map((unit) => unit.text)
+        .join(",\n"),
+    )
+    .join(",\n\n");
+  const lastUnit = groups.flatMap((group) => sortGroup(group)).at(-1);
+  const trailingComma = lastUnit?.property.type === "RestElement" ? "" : ",";
+
+  return {
+    needsFix: true,
+    replacement: `{\n${groupsText}${trailingComma}\n${lineIndent}}`,
+  };
+}
+
+export { getSortPlan, compareNames };