@mrpalmer/eslint-plugin 1.0.0

package/lib/rules/sort-named.js

@@ -0,0 +1,436 @@
+import { TSESTree } from '@typescript-eslint/utils';
+import { groupBy, reverse, findOutOfOrder } from '../utils/array.js';
+import { createRule } from '../utils/create-rule.js';
+//region rule
+// REPORTING AND FIXING
+function findSpecifierStart(sourceCode, node) {
+    let token;
+    do {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        token = sourceCode.getTokenBefore(node);
+    } while (token.value !== ',' && token.value !== '{');
+    return token.range[1];
+}
+function findSpecifierEnd(sourceCode, node) {
+    let token;
+    do {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        token = sourceCode.getTokenAfter(node);
+    } while (token.value !== ',' && token.value !== '}');
+    return token.range[0];
+}
+function isRequireExpression(expr) {
+    return (expr != null &&
+        expr.type === TSESTree.AST_NODE_TYPES.CallExpression &&
+        expr.callee.type === TSESTree.AST_NODE_TYPES.Identifier &&
+        expr.callee.name === 'require' &&
+        expr.arguments.length === 1 &&
+        expr.arguments[0].type === TSESTree.AST_NODE_TYPES.Literal);
+}
+function isCJSExports(context, node) {
+    if (node.type === TSESTree.AST_NODE_TYPES.MemberExpression &&
+        node.object.type === TSESTree.AST_NODE_TYPES.Identifier &&
+        node.property.type === TSESTree.AST_NODE_TYPES.Identifier &&
+        node.object.name === 'module' &&
+        node.property.name === 'exports') {
+        return !context.sourceCode
+            .getScope(node)
+            .variables.some((variable) => variable.name === 'module');
+    }
+    if (node.type === TSESTree.AST_NODE_TYPES.Identifier &&
+        node.name === 'exports') {
+        return !context.sourceCode
+            .getScope(node)
+            .variables.some((variable) => variable.name === 'exports');
+    }
+    return false;
+}
+function getNamedCJSExports(context, node) {
+    if (node.type !== TSESTree.AST_NODE_TYPES.MemberExpression) {
+        return undefined;
+    }
+    const result = [];
+    let root = node;
+    let parent;
+    while (root.type === TSESTree.AST_NODE_TYPES.MemberExpression) {
+        if (root.property.type !== TSESTree.AST_NODE_TYPES.Identifier) {
+            return undefined;
+        }
+        result.unshift(root.property.name);
+        parent = root;
+        root = root.object;
+    }
+    if (isCJSExports(context, root)) {
+        return result;
+    }
+    if (isCJSExports(context, parent)) {
+        return result.slice(1);
+    }
+    return undefined;
+}
+function makeImportDescription(node) {
+    if (node.type === 'export') {
+        if (node.node.exportKind === 'type') {
+            return 'type export';
+        }
+        return 'export';
+    }
+    if (node.node.importKind === 'type') {
+        return 'type import';
+    }
+    return 'import';
+}
+function fixOutOfOrder(context, firstNode, secondNode, order) {
+    const { sourceCode } = context;
+    const { firstRoot, secondRoot } = {
+        firstRoot: firstNode.node,
+        secondRoot: secondNode.node,
+    };
+    const { firstRootStart, firstRootEnd, secondRootStart, secondRootEnd } = {
+        firstRootStart: findSpecifierStart(sourceCode, firstRoot),
+        firstRootEnd: findSpecifierEnd(sourceCode, firstRoot),
+        secondRootStart: findSpecifierStart(sourceCode, secondRoot),
+        secondRootEnd: findSpecifierEnd(sourceCode, secondRoot),
+    };
+    if (firstNode.displayName === secondNode.displayName) {
+        if (firstNode.alias) {
+            firstNode.displayName = `${firstNode.displayName} as ${firstNode.alias}`;
+        }
+        if (secondNode.alias) {
+            secondNode.displayName = `${secondNode.displayName} as ${secondNode.alias}`;
+        }
+    }
+    const firstDesc = makeImportDescription(firstNode);
+    const secondDesc = makeImportDescription(secondNode);
+    if (firstNode.displayName === secondNode.displayName &&
+        firstDesc === secondDesc) {
+        return;
+    }
+    const firstImport = `${firstDesc} of \`${firstNode.displayName}\``;
+    const secondImport = `\`${secondNode.displayName}\` ${secondDesc}`;
+    const messageOptions = {
+        messageId: 'order',
+        data: { firstImport, secondImport, order },
+    };
+    const firstCode = sourceCode.text.slice(firstRootStart, firstRoot.range[1]);
+    const firstTrivia = sourceCode.text.slice(firstRoot.range[1], firstRootEnd);
+    const secondCode = sourceCode.text.slice(secondRootStart, secondRoot.range[1]);
+    const secondTrivia = sourceCode.text.slice(secondRoot.range[1], secondRootEnd);
+    if (order === 'before') {
+        const trimmedTrivia = secondTrivia.trimEnd();
+        const gapCode = sourceCode.text.slice(firstRootEnd, secondRootStart - 1);
+        const whitespaces = secondTrivia.slice(trimmedTrivia.length);
+        context.report({
+            node: secondNode.node,
+            ...messageOptions,
+            fix: (fixer) => fixer.replaceTextRange([firstRootStart, secondRootEnd], `${secondCode},${trimmedTrivia}${firstCode}${firstTrivia}${gapCode}${whitespaces}`),
+        });
+    }
+    else {
+        const trimmedTrivia = firstTrivia.trimEnd();
+        const gapCode = sourceCode.text.slice(secondRootEnd + 1, firstRootStart);
+        const whitespaces = firstTrivia.slice(trimmedTrivia.length);
+        context.report({
+            node: secondNode.node,
+            ...messageOptions,
+            fix: (fixes) => fixes.replaceTextRange([secondRootStart, firstRootEnd], `${gapCode}${firstCode},${trimmedTrivia}${secondCode}${whitespaces}`),
+        });
+    }
+}
+function reportOutOfOrder(context, imported, outOfOrder, order) {
+    for (const imp of outOfOrder) {
+        fixOutOfOrder(context, 
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        imported.find((importedItem) => importedItem.rank > imp.rank), imp, order);
+    }
+}
+function compareStrings(a, b) {
+    const aChunks = a
+        .replace(/(\d+)/g, '\0$1\0')
+        .replace(/^\0/, '')
+        .replace(/\0$/, '')
+        .split('\0');
+    const bChunks = b
+        .replace(/(\d+)/g, '\0$1\0')
+        .replace(/^\0/, '')
+        .replace(/\0$/, '')
+        .split('\0');
+    const maxLength = Math.max(aChunks.length, bChunks.length);
+    for (let i = 0; i < maxLength; i++) {
+        const aChunk = aChunks[i] ?? '';
+        const bChunk = bChunks[i] ?? '';
+        const aNum = Number(aChunk);
+        const bNum = Number(bChunk);
+        if (isNaN(aNum)) {
+            if (!isNaN(bNum)) {
+                return 1;
+            }
+        }
+        else if (isNaN(bNum)) {
+            return -1;
+        }
+        if (!isNaN(aNum) && !isNaN(bNum)) {
+            if (aNum !== bNum) {
+                return aNum - bNum;
+            }
+            if (aChunk !== bChunk) {
+                if (aChunk < bChunk) {
+                    return -1;
+                }
+                if (aChunk > bChunk) {
+                    return 1;
+                }
+            }
+            continue;
+        }
+        if (aChunk < bChunk) {
+            return -1;
+        }
+        if (aChunk > bChunk) {
+            return 1;
+        }
+    }
+    return 0;
+}
+const getNormalizedValue = (nodeValue, toLowerCase) => {
+    const value = String(nodeValue);
+    return toLowerCase ? value.toLowerCase() : value;
+};
+function getSorter(ignoreCase) {
+    function compareValues(valueA, valueB) {
+        const normalizedA = getNormalizedValue(valueA, ignoreCase);
+        const normalizedB = getNormalizedValue(valueB, ignoreCase);
+        return compareStrings(normalizedA, normalizedB);
+    }
+    return function importsSorter(nodeA, nodeB) {
+        if (nodeA.value === nodeB.value) {
+            if (nodeA.alias && nodeB.alias) {
+                return compareValues(nodeA.alias, nodeB.alias);
+            }
+            if (nodeA.alias) {
+                return 1;
+            }
+            if (nodeB.alias) {
+                return -1;
+            }
+            return 0;
+        }
+        return compareValues(nodeA.value, nodeB.value);
+    };
+}
+function mutateRanksToAlphabetize(imported, ignoreCase) {
+    const groupedByRanks = groupBy(imported, (item) => item.rank);
+    const sorterFn = getSorter(ignoreCase);
+    // sort group keys so that they can be iterated on in order
+    const groupRanks = Object.keys(groupedByRanks).sort((a, b) => +a - +b);
+    // sort imports locally within their group
+    for (const groupRank of groupRanks) {
+        groupedByRanks[groupRank].sort(sorterFn);
+    }
+    // assign globally unique rank to each import
+    let newRank = 0;
+    const alphabetizedRanks = groupRanks.reduce((acc, groupRank) => {
+        for (const importedItem of groupedByRanks[groupRank]) {
+            acc[`${importedItem.key}|${importedItem.node.importKind}`] =
+                Number.parseInt(groupRank, 10) + newRank;
+            newRank += 1;
+        }
+        return acc;
+    }, {});
+    // mutate the original group-rank with alphabetized-rank
+    for (const importedItem of imported) {
+        importedItem.rank =
+            alphabetizedRanks[`${importedItem.key}|${importedItem.node.importKind}`];
+    }
+}
+function makeOutOfOrderReport(context, imported) {
+    const outOfOrder = findOutOfOrder(imported);
+    if (outOfOrder.length === 0) {
+        return;
+    }
+    // There are things to report. Try to minimize the number of reported errors.
+    const reversedImported = reverse(imported);
+    const reversedOrder = findOutOfOrder(reversedImported);
+    if (reversedOrder.length < outOfOrder.length) {
+        reportOutOfOrder(context, reversedImported, reversedOrder, 'after');
+        return;
+    }
+    reportOutOfOrder(context, imported, outOfOrder, 'before');
+}
+function isSimpleObjectPropertyList(properties) {
+    return properties.every((p) => {
+        if (p.type !== TSESTree.AST_NODE_TYPES.Property) {
+            return false;
+        }
+        if (p.key.type !== TSESTree.AST_NODE_TYPES.Identifier) {
+            return false;
+        }
+        return p.value.type === TSESTree.AST_NODE_TYPES.Identifier;
+    });
+}
+export default createRule({
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Ensure named imports and exports are sorted consistently.',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    ignoreCase: {
+                        type: 'boolean',
+                    },
+                    types: {
+                        type: 'string',
+                        enum: ['mixed', 'types-first', 'types-last'],
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            order: '{{secondImport}} should occur {{order}} {{firstImport}}',
+        },
+    },
+    defaultOptions: [
+        {
+            ignoreCase: false,
+            types: 'types-first',
+        },
+    ],
+    create(context, [options]) {
+        const namedGroups = options.types === 'mixed'
+            ? []
+            : options.types === 'types-last'
+                ? ['value']
+                : ['type'];
+        const ignoreCase = options.ignoreCase ?? false;
+        const exportMap = new Map();
+        function getBlockExports(node) {
+            let blockExports = exportMap.get(node);
+            if (!blockExports) {
+                exportMap.set(node, (blockExports = []));
+            }
+            return blockExports;
+        }
+        function makeNamedOrderReport(context, namedImports) {
+            if (namedImports.length > 1) {
+                const imports = namedImports.map((namedImport) => {
+                    const kind = namedImport.kind ?? 'value';
+                    const rank = namedGroups.indexOf(kind);
+                    return {
+                        displayName: namedImport.value,
+                        key: `${namedImport.value}:${namedImport.alias ?? ''}`,
+                        rank: rank === -1 ? namedGroups.length : rank,
+                        ...namedImport,
+                    };
+                });
+                mutateRanksToAlphabetize(imports, ignoreCase);
+                makeOutOfOrderReport(context, imports);
+            }
+        }
+        return {
+            ImportDeclaration(node) {
+                if (node.specifiers.length === 0) {
+                    return;
+                }
+                makeNamedOrderReport(context, node.specifiers
+                    .filter((specifier) => specifier.type === TSESTree.AST_NODE_TYPES.ImportSpecifier)
+                    .map((specifier) => ({
+                    node: specifier,
+                    value: getValue(specifier.imported),
+                    type: 'import',
+                    kind: specifier.importKind,
+                    ...(specifier.local.range[0] !== specifier.imported.range[0] && {
+                        alias: specifier.local.name,
+                    }),
+                })));
+            },
+            VariableDeclarator(node) {
+                if (node.id.type === TSESTree.AST_NODE_TYPES.ObjectPattern &&
+                    isRequireExpression(node.init)) {
+                    const { properties } = node.id;
+                    if (!isSimpleObjectPropertyList(properties)) {
+                        return;
+                    }
+                    makeNamedOrderReport(context, properties.map((prop) => {
+                        const key = prop.key;
+                        const value = prop.value;
+                        return {
+                            node: prop,
+                            value: key.name,
+                            type: 'require',
+                            ...(key.range[0] !== value.range[0] && {
+                                alias: value.name,
+                            }),
+                        };
+                    }));
+                }
+            },
+            ExportNamedDeclaration(node) {
+                makeNamedOrderReport(context, node.specifiers.map((specifier) => ({
+                    node: specifier,
+                    value: getValue(specifier.local),
+                    type: 'export',
+                    kind: specifier.exportKind,
+                    ...(specifier.local.range[0] !== specifier.exported.range[0] && {
+                        alias: getValue(specifier.exported),
+                    }),
+                })));
+            },
+            AssignmentExpression(node) {
+                if (node.parent.type === TSESTree.AST_NODE_TYPES.ExpressionStatement) {
+                    if (isCJSExports(context, node.left)) {
+                        if (node.right.type === TSESTree.AST_NODE_TYPES.ObjectExpression) {
+                            const { properties } = node.right;
+                            if (!isSimpleObjectPropertyList(properties)) {
+                                return;
+                            }
+                            makeNamedOrderReport(context, properties.map((prop) => {
+                                const key = prop.key;
+                                const value = prop.value;
+                                return {
+                                    node: prop,
+                                    value: key.name,
+                                    type: 'export',
+                                    ...(key.range[0] !== value.range[0] && {
+                                        alias: value.name,
+                                    }),
+                                };
+                            }));
+                        }
+                    }
+                    else {
+                        const nameParts = getNamedCJSExports(context, node.left);
+                        if (nameParts && nameParts.length > 0) {
+                            const name = nameParts.join('.');
+                            getBlockExports(node.parent.parent).push({
+                                node,
+                                value: name,
+                                displayName: name,
+                                type: 'export',
+                                rank: 0,
+                                key: name,
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+});
+//endregion types
+//region utils
+function getValue(node) {
+    switch (node.type) {
+        case TSESTree.AST_NODE_TYPES.Identifier:
+            return node.name;
+        case TSESTree.AST_NODE_TYPES.Literal:
+            return node.value;
+        default:
+            throw new Error(`Unsupported node type: ${node.type}`);
+    }
+}
+//endregion

package/lib/types.d.ts

@@ -0,0 +1,12 @@
+import type { PluginName } from './constants.js';
+export type Arrayable<T> = T | readonly T[];
+export type LiteralNodeValue = string | number | bigint | boolean | RegExp | null;
+type WithPluginName<T extends string | object> = T extends string ? `${PluginName}/${T}` : {
+    [K in keyof T as WithPluginName<K & string>]: T[K];
+};
+export type PluginSettings = WithPluginName<{
+    tsconfig?: string;
+    coreModules?: string[];
+    internalRegex?: string;
+}>;
+export {};

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/array.d.ts

@@ -0,0 +1,6 @@
+export interface RankedItem {
+    rank: number;
+}
+export declare function reverse<T extends RankedItem>(array: T[]): T[];
+export declare function findOutOfOrder<T extends RankedItem>(array: T[]): T[];
+export declare function groupBy<T>(array: T[], grouper: (item: T, index: number) => string | number): Record<string, T[]>;

package/lib/utils/array.js

@@ -0,0 +1,23 @@
+export function reverse(array) {
+    return array.map((item) => ({ ...item, rank: -item.rank })).reverse();
+}
+export function findOutOfOrder(array) {
+    if (array.length === 0) {
+        return [];
+    }
+    let maxSeenRankItem = array[0];
+    return array.filter((item) => {
+        const res = item.rank < maxSeenRankItem.rank;
+        if (maxSeenRankItem.rank < item.rank) {
+            maxSeenRankItem = item;
+        }
+        return res;
+    });
+}
+export function groupBy(array, grouper) {
+    return array.reduce((acc, item, index) => {
+        const key = grouper(item, index);
+        (acc[key] ??= []).push(item);
+        return acc;
+    }, {});
+}

package/lib/utils/ast.d.ts

@@ -0,0 +1,4 @@
+import { type TSESLint, TSESTree } from '@typescript-eslint/utils';
+export declare function findRootNode(node: TSESTree.Node): TSESTree.Node;
+export declare function findEndOfLineWithComments(sourceCode: TSESLint.SourceCode, node: TSESTree.Node): number;
+export declare function findStartOfLineWithComments(sourceCode: TSESLint.SourceCode, node: TSESTree.Node): number;

package/lib/utils/ast.js

@@ -0,0 +1,102 @@
+import { TSESTree } from '@typescript-eslint/utils';
+export function findRootNode(node) {
+    let parent = node;
+    while (parent.parent != null &&
+        // eslint-disable-next-line eslint-plugin/no-property-in-node
+        (!('body' in parent.parent) || parent.parent.body == null)) {
+        parent = parent.parent;
+    }
+    return parent;
+}
+function getTokensOrCommentsAfter(sourceCode, node, count) {
+    let currentNodeOrToken = node;
+    const result = [];
+    for (let i = 0; i < count; i++) {
+        currentNodeOrToken = sourceCode.getTokenAfter(currentNodeOrToken, {
+            includeComments: true,
+        });
+        if (currentNodeOrToken == null) {
+            break;
+        }
+        result.push(currentNodeOrToken);
+    }
+    return result;
+}
+function getTokensOrCommentsBefore(sourceCode, node, count) {
+    let currentNodeOrToken = node;
+    const result = [];
+    for (let i = 0; i < count; i++) {
+        currentNodeOrToken = sourceCode.getTokenBefore(currentNodeOrToken, {
+            includeComments: true,
+        });
+        if (currentNodeOrToken == null) {
+            break;
+        }
+        result.push(currentNodeOrToken);
+    }
+    return result.reverse();
+}
+function takeTokensAfterWhile(sourceCode, node, condition) {
+    const tokens = getTokensOrCommentsAfter(sourceCode, node, 100);
+    const result = [];
+    for (const token of tokens) {
+        if (condition(token)) {
+            result.push(token);
+        }
+        else {
+            break;
+        }
+    }
+    return result;
+}
+function takeTokensBeforeWhile(sourceCode, node, condition) {
+    const tokens = getTokensOrCommentsBefore(sourceCode, node, 100);
+    const result = [];
+    for (let i = tokens.length - 1; i >= 0; i--) {
+        if (condition(tokens[i])) {
+            result.push(tokens[i]);
+        }
+        else {
+            break;
+        }
+    }
+    return result.reverse();
+}
+export function findEndOfLineWithComments(sourceCode, node) {
+    const tokensToEndOfLine = takeTokensAfterWhile(sourceCode, node, commentOnSameLineAs(node));
+    const endOfTokens = tokensToEndOfLine.length > 0
+        ? tokensToEndOfLine[tokensToEndOfLine.length - 1].range[1]
+        : node.range[1];
+    let result = endOfTokens;
+    for (let i = endOfTokens; i < sourceCode.text.length; i++) {
+        if (sourceCode.text[i] === '\n') {
+            result = i + 1;
+            break;
+        }
+        if (sourceCode.text[i] !== ' ' &&
+            sourceCode.text[i] !== '\t' &&
+            sourceCode.text[i] !== '\r') {
+            break;
+        }
+        result = i + 1;
+    }
+    return result;
+}
+function commentOnSameLineAs(node) {
+    return (token) => (token.type === TSESTree.AST_TOKEN_TYPES.Block ||
+        token.type === TSESTree.AST_TOKEN_TYPES.Line) &&
+        token.loc.start.line === token.loc.end.line &&
+        token.loc.end.line === node.loc.end.line;
+}
+export function findStartOfLineWithComments(sourceCode, node) {
+    const tokensToEndOfLine = takeTokensBeforeWhile(sourceCode, node, commentOnSameLineAs(node));
+    const startOfTokens = tokensToEndOfLine.length > 0 ? tokensToEndOfLine[0].range[0] : node.range[0];
+    let result = startOfTokens;
+    for (let i = startOfTokens - 1; i > 0; i--) {
+        if (sourceCode.text[i] !== ' ' && sourceCode.text[i] !== '\t') {
+            break;
+        }
+        result = i;
+    }
+    return result;
+}

package/lib/utils/create-rule.d.ts

@@ -0,0 +1,2 @@
+import type { ESLintUtils } from '@typescript-eslint/utils';
+export declare const createRule: typeof ESLintUtils.RuleCreator.withoutDocs;

package/lib/utils/create-rule.js

@@ -0,0 +1,58 @@
+export const createRule = function createRule({ create, defaultOptions, meta }) {
+    return {
+        meta,
+        defaultOptions,
+        create(context) {
+            const optionsWithDefaults = applyDefaults(defaultOptions, context.options);
+            return create(context, optionsWithDefaults);
+        },
+    };
+};
+function applyDefaults(defaultOptions, userOptions) {
+    // clone defaults
+    const options = structuredClone(defaultOptions);
+    if (userOptions == null) {
+        return options;
+    }
+    ;
+    options.forEach((opt, i) => {
+        if (userOptions[i] !== undefined) {
+            const userOpt = userOptions[i];
+            if (isObjectNotArray(userOpt) && isObjectNotArray(opt)) {
+                options[i] = deepMerge(opt, userOpt);
+            }
+            else {
+                options[i] = userOpt;
+            }
+        }
+    });
+    return options;
+}
+function isObjectNotArray(obj) {
+    return typeof obj === 'object' && obj != null && !Array.isArray(obj);
+}
+function deepMerge(first, second) {
+    const keys = new Set([...Object.keys(first), ...Object.keys(second)]);
+    return Object.fromEntries([...keys].map((key) => {
+        const firstHasKey = key in first;
+        const secondHasKey = key in second;
+        const firstValue = first[key];
+        const secondValue = second[key];
+        let value;
+        if (firstHasKey && secondHasKey) {
+            if (isObjectNotArray(firstValue) && isObjectNotArray(secondValue)) {
+                value = deepMerge(firstValue, secondValue);
+            }
+            else {
+                value = secondValue;
+            }
+        }
+        else if (firstHasKey) {
+            value = firstValue;
+        }
+        else {
+            value = secondValue;
+        }
+        return [key, value];
+    }));
+}

package/lib/utils/import-path-options.d.ts

@@ -0,0 +1,6 @@
+import { type TsConfigResult } from 'get-tsconfig';
+export declare function getImportPathOptions({ originalPath, filePath, tsconfig, }: {
+    originalPath: string;
+    filePath: string;
+    tsconfig: TsConfigResult | undefined;
+}): Set<string>;