prettier-plugin-sort 0.2.0 → 1.0.0

package/dist/options.d.ts

@@ -1,26 +1,23 @@
 import { type ParserOptions, type SupportOptions } from 'prettier';
-/** import 分组，参考 eslint-plugin-import 的 import/order 规则。 */
+/** import 声明分组。 */
 export type ImportGroup = 'builtin' | 'external' | 'internal' | 'parent' | 'sibling' | 'index';
-/** `import type` 内联风格，参考 @typescript-eslint/consistent-type-imports 的 fixStyle 选项。 */
-export type TypeImportsStyle = 'separate' | 'inline-first' | 'inline-last' | 'mixed';
+/** type import 的声明形式与成员顺序。 */
+export type TypeImportStyle = 'separate' | 'inline-first' | 'inline-last' | 'mixed';
 /** 插件排序配置。 */
 export interface SortOptions {
-    importOrder?: boolean;
-    importOrderGroups?: ImportGroup[];
-    importOrderSeparation?: boolean;
-    importOrderTypeImports?: TypeImportsStyle;
-    importOrderMergeDuplicates?: boolean;
-    exportOrder?: boolean;
-    packageJsonOrder?: boolean;
-    packageJsonOrderExcludeKeys?: string[];
+    esmImportSort?: boolean;
+    esmImportGroups?: ImportGroup[];
+    esmImportSeparation?: boolean;
+    esmImportTypeStyle?: TypeImportStyle;
+    esmImportMerge?: boolean;
+    esmExportSpecifierSort?: boolean;
+    packageSort?: boolean;
 }
-/** 默认排序配置。 */
-export declare const DEFAULT_SORT_OPTIONS: Required<SortOptions>;
-type RawSortOptions = ParserOptions & Partial<SortOptions>;
+type SortPluginParserOptions = ParserOptions & SortOptions;
 /**
  * 从 Prettier 选项中提取插件配置，缺失或非法的参数会回退为默认值。
  */
-export declare function resolveSortOptions(rawOptions: RawSortOptions): Required<SortOptions>;
-/** 注册到 Prettier 的选项定义。使用功能名词前缀命名，因为 Prettier API 不支持嵌套的选项对象。 */
+export declare function resolveSortOptions(prettierOptions: SortPluginParserOptions): Required<SortOptions>;
+/** Prettier 插件选项。 */
 export declare const options: SupportOptions;
 export {};

package/dist/parser-ast.d.ts

@@ -0,0 +1,78 @@
+import { type SourceTextRange } from './utils/source-text';
+/**
+ * 已注册 Prettier parser 的源码偏移字段。
+ *
+ * `start`/`end` 是 Babel AST 使用的绝对偏移。
+ * `range` 是 typescript-estree 等 ESTree 兼容 AST 使用的 `[start, end]` 偏移元组。
+ *
+ * @see {@link https://babeljs.io/docs/babel-parser#options | Babel parser 位置选项}
+ * @see {@link https://typescript-eslint.io/packages/typescript-estree/#api | typescript-estree 的 range 选项}
+ */
+interface ParserAstLocation extends Record<string, unknown> {
+    readonly start?: number;
+    readonly end?: number;
+    readonly range?: readonly [number, number];
+}
+/**
+ * 排序逻辑使用的跨 parser AST 字段。
+ *
+ * 字段均来自已注册 parser 的上游 AST：
+ *
+ * - `type`、`name`、`value`、`body` 来自 ESTree 基础节点
+ * - `declaration`、`specifiers`、`source`、`imported`、`local`、`exported` 来自 ESTree ES2015 module 节点
+ * - `program`、`comments` 来自 Babel `File` 包装节点及 Prettier 的顶层注释约定
+ * - `importKind`、`phase` 来自 Babel/typescript-estree 的 import 扩展
+ *
+ * 不同 parser 的字段结构存在差异，因此属性均为可选，并在使用处收窄类型。
+ *
+ * @see {@link https://github.com/estree/estree/blob/master/es5.md#node-objects | ESTree 基础节点}
+ * @see {@link https://github.com/estree/estree/blob/master/es2015.md#modules | ESTree module 节点}
+ * @see {@link https://babeljs.io/docs/babel-types#file | Babel File 节点}
+ * @see {@link https://babeljs.io/docs/babel-types#importdeclaration | Babel ImportDeclaration 节点}
+ * @see {@link https://typescript-eslint.io/packages/typescript-estree/ast-spec/#importdeclaration | typescript-estree ImportDeclaration 节点}
+ * @see {@link https://prettier.io/docs/plugins#handling-comments-in-a-printer | Prettier 顶层注释约定}
+ */
+export interface ParserAstNode extends ParserAstLocation {
+    readonly type: string;
+    readonly name?: unknown;
+    readonly value?: unknown;
+    readonly body?: ParserAstNode[];
+    readonly comments?: ParserAstComment[];
+    readonly program?: ParserAstNode;
+    readonly declaration?: ParserAstNode | null;
+    readonly specifiers?: ParserAstNode[];
+    readonly source?: ParserAstNode | null;
+    readonly imported?: ParserAstNode | null;
+    readonly local?: ParserAstNode | null;
+    readonly exported?: ParserAstNode | null;
+    readonly importKind?: unknown;
+    readonly phase?: unknown;
+}
+/**
+ * 排序逻辑使用的 parser 注释字段。
+ *
+ * `value` 是不含注释分隔符的正文；源码偏移来自 parser 节点的 `start`/`end` 或 `range`。
+ *
+ * @see {@link https://prettier.io/docs/plugins#handling-comments-in-a-printer | Prettier 注释节点约定}
+ */
+export interface ParserAstComment extends ParserAstLocation {
+    readonly value?: unknown;
+}
+export interface ParserAstCommentWithTextRange {
+    readonly comment: ParserAstComment;
+    readonly textRange: SourceTextRange;
+}
+export declare function getAstNodeTextRange(node: ParserAstNode | ParserAstComment | undefined | null): SourceTextRange | null;
+export declare function getSortedAstCommentsWithTextRanges(comments: readonly ParserAstComment[]): ParserAstCommentWithTextRange[];
+/** 使用二分查找定位指定源码位置之后的第一条注释。 */
+export declare function findCommentIndexAtOrAfter(sortedComments: readonly ParserAstCommentWithTextRange[], sourceIndex: number): number;
+export declare function getAstNodeName(node: ParserAstNode | undefined | null): string | null;
+export declare function getAstCommentText(comment: ParserAstComment): string | null;
+export declare function getProgramStatements(parserAst: ParserAstNode): readonly ParserAstNode[];
+export declare function getProgramComments(parserAst: ParserAstNode): readonly ParserAstComment[];
+export declare function isSourceRangeWhitespaceOrComments(sourceText: string, sourceRange: SourceTextRange, sortedComments: readonly ParserAstCommentWithTextRange[]): boolean;
+/**
+ * Prettier 会在解析器预处理之后才附着 `prettier-ignore` 注释，因此文本变换必须先自行识别。
+ */
+export declare function isPrettierIgnored(sourceText: string, statementRange: SourceTextRange, sortedComments: readonly ParserAstCommentWithTextRange[]): boolean;
+export {};

package/dist/sort-exports.d.ts

@@ -1,12 +1,9 @@
-import { type ParserOptions } from 'prettier';
+import { type ParserAstCommentWithTextRange, type ParserAstNode } from './parser-ast';
+import { type SourceTextEdit } from './utils/source-text';
 /**
- * 按字母序排列 `export { … }` 花括号内的命名导出。
- * 不改变语句位置，不跨语句合并，只针对单条 export 语句的花括号内部。
+ * 为无注释的 `export { ... }` 生成 specifier 排序编辑。
  *
- * 覆盖的语法形式：
- *   export { a, b };
- *   export { a, b } from 'mod';
- *   export type { A, B };
- *   export type { A, B } from 'mod';
+ * 注释位于逗号两侧时，仅靠 parser 暴露的裸 AST 无法可靠判断它属于前一项还是后一项。
+ * 遇到这种声明时保持原样，避免为了排序改变注释语义。
  */
-export declare function sortExports(text: string, rawOptions: ParserOptions): string;
+export declare function buildExportSortingEdits(sourceText: string, programStatements: readonly ParserAstNode[], sortedComments: readonly ParserAstCommentWithTextRange[]): SourceTextEdit[];

package/dist/sort-imports.d.ts

@@ -1,2 +1,8 @@
-import { type ParserOptions } from 'prettier';
-export declare function sortImports(text: string, rawOptions: ParserOptions): string;
+import { type SortOptions } from './options';
+import { type ParserAstCommentWithTextRange, type ParserAstNode } from './parser-ast';
+import { type SourceTextEdit } from './utils/source-text';
+/**
+ * 将顶层 import 划分为可独立排序的片段，并生成基于原文范围的编辑。
+ * 被忽略的声明、独立注释和位置敏感指令不会进入编辑范围。
+ */
+export declare function buildImportSortingEdits(sourceText: string, programStatements: readonly ParserAstNode[], sortedComments: readonly ParserAstCommentWithTextRange[], sortOptions: Required<SortOptions>, isPrettierFilePragmaPresent: boolean): SourceTextEdit[];

package/dist/sort-package.d.ts

@@ -1,2 +1,6 @@
-import { type ParserOptions } from 'prettier';
-export declare function sortPackageJson(text: string, rawOptions: ParserOptions): string;
+import { type Parser, type ParserOptions } from 'prettier';
+/**
+ * 只处理 package.json。
+ * 解析失败、AST 结构不完整或数字无法还原时直接返回原文。
+ */
+export declare function preprocessPackageJson(sourceText: string, prettierOptions: ParserOptions, parser: Parser): Promise<string>;

package/dist/sort-typescript.d.ts

@@ -0,0 +1,6 @@
+import { type Parser, type ParserOptions } from 'prettier';
+/**
+ * 顶层 ES module 排序事务：原文只解析一次，所有编辑都基于同一份 AST 范围生成。
+ * 编辑应用后再次解析；范围冲突或无效语法都会让整次变换返回原文。
+ */
+export declare function sortTypeScript(sourceText: string, prettierOptions: ParserOptions, parser: Parser): Promise<string>;

package/dist/utils/package-rules.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 基于 `sort-package-json` 4.0.0 默认规则的 `package.json` 顶层字段顺序。
+ *
+ * @see {@link https://github.com/keithamus/sort-package-json/blob/v4.0.0/defaultRules.md | sort-package-json 4.0.0 默认规则}
+ */
+export declare const PACKAGE_JSON_FIELD_ORDER: readonly ["$schema", "name", "displayName", "version", "stableVersion", "private", "description", "categories", "keywords", "homepage", "bugs", "repository", "funding", "license", "qna", "author", "maintainers", "contributors", "publisher", "sideEffects", "type", "imports", "exports", "main", "svelte", "umd:main", "jsdelivr", "unpkg", "module", "source", "jsnext:main", "browser", "react-native", "types", "typesVersions", "typings", "style", "example", "examplestyle", "assets", "bin", "man", "directories", "files", "workspaces", "binary", "scripts", "betterScripts", "wireit", "l10n", "contributes", "activationEvents", "husky", "simple-git-hooks", "pre-commit", "commitlint", "lint-staged", "nano-staged", "config", "nodemonConfig", "browserify", "babel", "browserslist", "xo", "prettier", "eslintConfig", "eslintIgnore", "npmpkgjsonlint", "npmPackageJsonLintConfig", "npmpackagejsonlint", "release", "remarkConfig", "stylelint", "ava", "jest", "jest-junit", "jest-stare", "mocha", "nyc", "c8", "tap", "oclif", "resolutions", "overrides", "dependencies", "devDependencies", "dependenciesMeta", "peerDependencies", "peerDependenciesMeta", "optionalDependencies", "bundledDependencies", "bundleDependencies", "extensionPack", "extensionDependencies", "flat", "packageManager", "engines", "engineStrict", "devEngines", "volta", "languageName", "os", "cpu", "preferGlobal", "publishConfig", "icon", "badges", "galleryBanner", "preview", "markdown", "pnpm"];
+export declare const DIRECTORY_FIELD_ORDER: readonly ["lib", "bin", "man", "doc", "example", "test"];
+export declare const ESLINT_CONFIG_FIELD_ORDER: readonly ["files", "excludedFiles", "env", "parser", "parserOptions", "settings", "plugins", "extends", "rules", "overrides", "globals", "processor", "noInlineConfig", "reportUnusedDisableDirectives"];
+export declare const GIT_HOOK_ORDER: readonly ["applypatch-msg", "pre-applypatch", "post-applypatch", "pre-commit", "pre-merge-commit", "prepare-commit-msg", "commit-msg", "post-commit", "pre-rebase", "post-checkout", "post-merge", "pre-push", "pre-receive", "update", "proc-receive", "post-receive", "post-update", "reference-transaction", "push-to-checkout", "pre-auto-gc", "post-rewrite", "sendemail-validate", "fsmonitor-watchman", "p4-changelist", "p4-prepare-changelist", "p4-post-changelist", "p4-pre-submit", "post-index-change"];
+export declare const NPM_LIFECYCLE_SCRIPT_NAMES: ReadonlySet<string>;
+export declare const PNPM_CONFIG_FIELD_ORDER: readonly ["peerDependencyRules", "neverBuiltDependencies", "onlyBuiltDependencies", "onlyBuiltDependenciesFile", "allowedDeprecatedVersions", "allowNonAppliedPatches", "updateConfig", "auditConfig", "requiredScripts", "supportedArchitectures", "overrides", "patchedDependencies", "packageExtensions"];
+export declare const WIREIT_SCRIPT_FIELD_ORDER: readonly ["command", "dependencies", "files", "output"];

package/dist/utils/source-text.d.ts

@@ -0,0 +1,9 @@
+export interface SourceTextRange {
+    start: number;
+    end: number;
+}
+export interface SourceTextEdit extends SourceTextRange {
+    replacementText: string;
+}
+/** 校验全部范围后倒序应用编辑；范围无效或相互重叠时返回 null。 */
+export declare function applySourceTextEdits(sourceText: string, sourceTextEdits: readonly SourceTextEdit[]): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "prettier-plugin-sort",
-  "version": "0.2.0",
-  "description": "An all-in-one Prettier plugin to sort imports, package.json keys, and more.",
+  "version": "1.0.0",
+  "description": "A Prettier plugin for sorting ES module imports, export specifiers, and package.json keys.",
   "keywords": [
     "imports",
     "order",
@@ -35,28 +35,32 @@
     "dist"
   ],
   "scripts": {
-    "build": "bun run scripts/build/",
-    "format": "prettier **/*.ts --write",
-    "lint": "eslint **/*.ts",
+    "build": "bun run scripts/build.ts",
+    "format": "prettier **/*.{json,ts,md} --write --experimental-cli",
+    "lint": "eslint src/ --cache",
+    "lint:fix": "eslint src/ --fix --cache",
     "prepare": "husky",
-    "test": "bun test scripts/test/",
+    "test": "bun test tests/",
     "typecheck": "tsc --noEmit"
   },
+  "dependencies": {
+    "semver": "^7.8.5"
+  },
   "devDependencies": {
     "@commitlint/cli": "^21.0.1",
     "@commitlint/config-conventional": "^21.0.1",
     "@commitlint/types": "^21.0.1",
     "@eslint/js": "^10.0.1",
     "@types/bun": "^1.3.14",
+    "@types/semver": "^7.7.1",
     "annal": "^0.0.2",
     "eslint": "^10.4.0",
     "husky": "^9.1.7",
-    "prettier": "^3.8.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.3"
   },
   "peerDependencies": {
-    "prettier": ">=3.0.0"
+    "prettier": ">=3.9.0 <4"
   },
   "devEngines": {
     "runtime": {

package/dist/order-package.d.ts

@@ -1,10 +0,0 @@
-/**
- * `package.json` 顶层字段的排列顺序。
- * 参考社区标准 sort-package-json 的字段列表：https://github.com/keithamus/sort-package-json/blob/main/index.js#L433-L564
- */
-export declare const PACKAGE_JSON_TOP_LEVEL_ORDER: readonly string[];
-/**
- * 值为 `{ name: range }` 映射的依赖表字段。
- * 始终按字母序排列，不受用户选项影响——npm install 每次都会按字母序重写。
- */
-export declare const DEPENDENCY_FIELDS: readonly string[];

package/dist/utils.d.ts

@@ -1,8 +0,0 @@
-/**
- * 按 `separator` 分割字符串，忽略嵌套在 `{}` / `()` / `[]` 中的分隔符。
- * 仅在顶层（深度为 0 的位置）分隔。返回结果会 trim 并剔除空段。
- *
- * 不使用 `String.prototype.split` 直接分隔，因为 import / export 的花括号内可能
- * 出现形如 `{ a, b as c }`，其中嵌套结构内的逗号不应被当作分隔符。
- */
-export declare function splitTopLevel(input: string, separator: string): string[];