eslint-plugin-imports-regulation 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+declare const _default: {
+    configs: {
+        recommended: {
+            plugins: {
+                'imports-regulation': {
+                    meta: {
+                        name: string;
+                    };
+                    rules: {
+                        'imports-regulation': import("@typescript-eslint/utils/ts-eslint").RuleModule<"groupOrder" | "blankLines" | "unexpectedBlankLine" | "typeSpecifiersLast" | "markTypeOnly" | "inlineTypeSpecifiers" | "afterImports", [{
+                            local?: string[];
+                            patterns?: {
+                                pattern: string;
+                                group: "package" | "local";
+                            }[];
+                            blankLines?: number;
+                            afterImports?: number;
+                            addenda?: string[];
+                            typeOnly?: "declaration" | "inline" | "ignore";
+                        }?], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener>;
+                    };
+                };
+            };
+            rules: {
+                'imports-regulation/imports-regulation': string;
+            };
+        };
+    };
+    meta: {
+        name: string;
+    };
+    rules: {
+        'imports-regulation': import("@typescript-eslint/utils/ts-eslint").RuleModule<"groupOrder" | "blankLines" | "unexpectedBlankLine" | "typeSpecifiersLast" | "markTypeOnly" | "inlineTypeSpecifiers" | "afterImports", [{
+            local?: string[];
+            patterns?: {
+                pattern: string;
+                group: "package" | "local";
+            }[];
+            blankLines?: number;
+            afterImports?: number;
+            addenda?: string[];
+            typeOnly?: "declaration" | "inline" | "ignore";
+        }?], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener>;
+    };
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,10 @@
+import importsRegulation from './rules/imports-regulation.js';
+const plugin = {
+    meta: { name: 'eslint-plugin-imports-regulation' },
+    rules: { 'imports-regulation': importsRegulation },
+};
+const recommended = {
+    plugins: { 'imports-regulation': plugin },
+    rules: { 'imports-regulation/imports-regulation': 'warn' },
+};
+export default { ...plugin, configs: { recommended } };

package/dist/rules/imports-regulation.d.ts

@@ -0,0 +1,19 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+type MessageIds = 'groupOrder' | 'blankLines' | 'unexpectedBlankLine' | 'typeSpecifiersLast' | 'markTypeOnly' | 'inlineTypeSpecifiers' | 'afterImports';
+type Locality = 'package' | 'local';
+type TypeOnlyStyle = 'declaration' | 'inline' | 'ignore';
+type Options = [
+    {
+        local?: string[];
+        patterns?: {
+            pattern: string;
+            group: Locality;
+        }[];
+        blankLines?: number;
+        afterImports?: number;
+        addenda?: string[];
+        typeOnly?: TypeOnlyStyle;
+    }?
+];
+declare const rule: TSESLint.RuleModule<MessageIds, Options>;
+export default rule;

package/dist/rules/imports-regulation.js

@@ -0,0 +1,350 @@
+const DEFAULT_BLANK_LINES = 1;
+const DEFAULT_AFTER_IMPORTS = 2;
+const DEFAULT_TYPE_ONLY = 'declaration';
+// The order, as written. The blank line falls between 1 and 2 — nowhere else.
+const PACKAGE_TYPE = 0;
+const LOCAL_TYPE = 2;
+const GROUP_NAMES = ['package type-only', 'package', 'local type-only', 'local'];
+const BREAK = /\r\n|\n|\r/;
+const BREAK_GLOBAL = /\r\n|\n|\r/g;
+const nameOfGroup = (group) => GROUP_NAMES[group] ?? 'other';
+const isLocalGroup = (group) => group >= LOCAL_TYPE;
+const escapeRegExp = (text) => text.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+/** `*` stops at a `/`, `**` does not — module specifiers are path-shaped. */
+const globToRegExp = (glob) => {
+    const body = glob
+        .split('**')
+        .map(part => escapeRegExp(part).replace(/\*/g, '[^/]*').replace(/\?/g, '[^/]'))
+        .join('.*');
+    return new RegExp(`^${body}$`);
+};
+/** A line is not path-shaped, so here `*` matches anything at all. */
+const lineGlobToRegExp = (glob) => new RegExp(`^${escapeRegExp(glob).replace(/\*/g, '.*').replace(/\?/g, '.')}$`);
+const rule = {
+    defaultOptions: [],
+    meta: {
+        type: 'layout',
+        docs: {
+            description: 'Group imports as package type-only, package, blank line, local type-only, local, with type specifiers last inside each import',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    // Prefixes that mean "mine", alongside the relative paths that always do.
+                    local: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+                    // Globs against the raw specifier, consulted before anything else. First match wins.
+                    patterns: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                pattern: { type: 'string' },
+                                group: { type: 'string', enum: ['package', 'local'] },
+                            },
+                            required: ['pattern', 'group'],
+                            additionalProperties: false,
+                        },
+                    },
+                    // How many blank lines separate the package block from the local block. 0 means none.
+                    blankLines: { type: 'integer', minimum: 0 },
+                    // How many blank lines separate the imports from whatever follows them.
+                    afterImports: { type: 'integer', minimum: 0 },
+                    // Line globs that still count as part of the imports block, so the gap is measured
+                    // after them rather than after the last import.
+                    addenda: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+                    typeOnly: { type: 'string', enum: ['declaration', 'inline', 'ignore'] },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            groupOrder: 'A {{group}} import must come before {{other}} imports.',
+            blankLines: 'Expected {{expected}} blank {{lines}} between package imports and local imports, found {{actual}}.',
+            unexpectedBlankLine: 'Unexpected blank line between imports in the same group.',
+            typeSpecifiersLast: 'Type specifiers must come after value specifiers.',
+            markTypeOnly: 'An import of nothing but types must be written `import type { A }`.',
+            inlineTypeSpecifiers: 'A type-only import must mark each specifier: `import { type A }`.',
+            afterImports: 'Expected {{expected}} blank {{lines}} after the imports, found {{actual}}.',
+        },
+    },
+    create(context) {
+        const source = context.sourceCode;
+        const localPrefixes = context.options[0]?.local ?? [];
+        const patterns = (context.options[0]?.patterns ?? []).map(entry => ({
+            test: globToRegExp(entry.pattern),
+            group: entry.group,
+        }));
+        const blankLines = context.options[0]?.blankLines ?? DEFAULT_BLANK_LINES;
+        const afterImports = context.options[0]?.afterImports ?? DEFAULT_AFTER_IMPORTS;
+        const addenda = (context.options[0]?.addenda ?? []).map(lineGlobToRegExp);
+        const typeOnly = context.options[0]?.typeOnly ?? DEFAULT_TYPE_ONLY;
+        const eol = BREAK.exec(source.text)?.[0] ?? '\n';
+        const localityOf = (path) => {
+            for (const { test, group } of patterns)
+                if (test.test(path))
+                    return group;
+            if (path === '.' || path === '..' || path.startsWith('./') || path.startsWith('../'))
+                return 'local';
+            if (localPrefixes.some(prefix => path.startsWith(prefix)))
+                return 'local';
+            return 'package';
+        };
+        const namedOf = (node) => {
+            const named = [];
+            for (const specifier of node.specifiers) {
+                if (specifier.type === 'ImportSpecifier')
+                    named.push(specifier);
+            }
+            return named;
+        };
+        // Nothing but inline `type` specifiers: a type-only import that has not said so, and so would
+        // otherwise sort into the value group.
+        const unmarkedTypeOnly = (node) => node.importKind === 'value'
+            && node.specifiers.length > 0
+            && node.specifiers.every(s => s.type === 'ImportSpecifier' && s.importKind === 'type');
+        const groupOf = (node) => {
+            const typeOnly = node.importKind === 'type' || unmarkedTypeOnly(node);
+            const base = localityOf(node.source.value) === 'local' ? LOCAL_TYPE : PACKAGE_TYPE;
+            return typeOnly ? base : base + 1;
+        };
+        const braceInterior = (named) => {
+            const first = named[0];
+            const last = named[named.length - 1];
+            if (!first || !last)
+                return undefined;
+            const open = source.getTokenBefore(first, { filter: token => token.value === '{' });
+            const close = source.getTokenAfter(last, { filter: token => token.value === '}' });
+            if (!open || !close)
+                return undefined;
+            return [open.range[1], close.range[0]];
+        };
+        /** Re-join specifiers in the shape the braces already had, so a multi-line import stays one. */
+        const rejoin = (range, texts) => {
+            const interior = source.text.slice(range[0], range[1]);
+            if (!BREAK.test(interior)) {
+                const pad = /^\s/.test(interior) ? ' ' : '';
+                return `${pad}${texts.join(', ')}${pad}`;
+            }
+            const indent = /(?:\r\n|\n|\r)([^\S\r\n]*)\S/.exec(interior)?.[1] ?? '    ';
+            const closeIndent = /(?:\r\n|\n|\r)([^\S\r\n]*)$/.exec(interior)?.[1] ?? '';
+            const comma = /,\s*$/.test(interior) ? ',' : '';
+            return `${eol}${indent}${texts.join(`,${eol}${indent}`)}${comma}${eol}${closeIndent}`;
+        };
+        const asValueSpecifier = (specifier) => {
+            const imported = source.getText(specifier.imported);
+            if (specifier.imported.type === 'Identifier' && specifier.imported.name === specifier.local.name) {
+                return imported;
+            }
+            return `${imported} as ${specifier.local.name}`;
+        };
+        const checkSpecifiers = (node) => {
+            const named = namedOf(node);
+            const range = braceInterior(named);
+            if (!range)
+                return;
+            if (node.importKind === 'type') {
+                // A default or namespace import has nowhere to put an inline marker, so it stays as it is.
+                if (typeOnly !== 'inline' || named.length !== node.specifiers.length)
+                    return;
+                const keyword = source.getFirstToken(node);
+                const marker = keyword ? source.getTokenAfter(keyword) : undefined;
+                if (!keyword || !marker || marker.value !== 'type')
+                    return;
+                context.report({
+                    node,
+                    messageId: 'inlineTypeSpecifiers',
+                    fix: fixer => [
+                        fixer.removeRange([keyword.range[1], marker.range[1]]),
+                        fixer.replaceTextRange(range, rejoin(range, named.map(specifier => `type ${source.getText(specifier)}`))),
+                    ],
+                });
+                return;
+            }
+            if (typeOnly === 'declaration' && unmarkedTypeOnly(node)) {
+                const keyword = source.getFirstToken(node);
+                if (!keyword)
+                    return;
+                context.report({
+                    node,
+                    messageId: 'markTypeOnly',
+                    fix: fixer => [
+                        fixer.insertTextAfter(keyword, ' type'),
+                        fixer.replaceTextRange(range, rejoin(range, named.map(asValueSpecifier))),
+                    ],
+                });
+                return;
+            }
+            const values = [];
+            const types = [];
+            for (const specifier of named) {
+                if (specifier.importKind === 'type')
+                    types.push(specifier);
+                else
+                    values.push(specifier);
+            }
+            if (types.length === 0 || values.length === 0)
+                return;
+            const firstType = named.findIndex(specifier => specifier.importKind === 'type');
+            const misplaced = named.slice(firstType).find(specifier => specifier.importKind !== 'type');
+            if (!misplaced)
+                return;
+            context.report({
+                node: misplaced,
+                messageId: 'typeSpecifiersLast',
+                fix: fixer => fixer.replaceTextRange(range, rejoin(range, [...values, ...types].map(specifier => source.getText(specifier)))),
+            });
+        };
+        /** An import plus the comments that travel with it. */
+        const entriesOf = (chunk) => {
+            const entries = [];
+            for (const node of chunk) {
+                const previous = entries[entries.length - 1];
+                let start = node.range[0];
+                // An own-line comment belongs to the import beneath it. One above the *first* import of
+                // a chunk is left where it is, being as likely a file header as a note about the import.
+                if (previous) {
+                    for (const comment of source.getCommentsBefore(node)) {
+                        if (comment.range[0] >= previous.end) {
+                            start = comment.range[0];
+                            break;
+                        }
+                    }
+                }
+                let end = node.range[1];
+                const trailing = source.getCommentsAfter(node)[0];
+                if (trailing && trailing.loc.start.line === node.loc.end.line)
+                    end = trailing.range[1];
+                entries.push({ node, group: groupOf(node), start, end });
+            }
+            return entries;
+        };
+        const lineAt = (index) => source.lines[index] ?? '';
+        const isBlank = (index) => lineAt(index).trim() === '';
+        /**
+         * Blank lines between the imports block and whatever follows it.
+         *
+         * Line-based rather than node-based, because `addenda` is about lines: a blank line or a line
+         * matching one of those globs is still part of the block, so the gap starts after the last of
+         * them. Nothing is reported at end of file — trailing blank lines belong to `start-end-lines`.
+         */
+        const checkAfterImports = (last) => {
+            // `source.lines` is 0-based, so line N sits at index N - 1 and index N is the line after it
+            let cursor = source.getLocFromIndex(last.end).line;
+            let blockEnd = cursor;
+            while (cursor < source.lines.length) {
+                if (isBlank(cursor))
+                    cursor++;
+                else if (addenda.some(pattern => pattern.test(lineAt(cursor).trim())))
+                    blockEnd = ++cursor;
+                else
+                    break;
+            }
+            let next = blockEnd;
+            while (next < source.lines.length && isBlank(next))
+                next++;
+            if (next >= source.lines.length)
+                return;
+            const blank = next - blockEnd;
+            if (blank === afterImports)
+                return;
+            const from = source.getIndexFromLoc({ line: blockEnd, column: lineAt(blockEnd - 1).length });
+            const to = source.getIndexFromLoc({ line: next + 1, column: 0 });
+            context.report({
+                node: last.node,
+                messageId: 'afterImports',
+                data: {
+                    expected: String(afterImports),
+                    actual: String(blank),
+                    lines: afterImports === 1 ? 'line' : 'lines',
+                },
+                fix: fixer => fixer.replaceTextRange([from, to], eol.repeat(afterImports + 1)),
+            });
+        };
+        const checkChunk = (chunk) => {
+            const entries = entriesOf(chunk);
+            const first = entries[0];
+            const last = entries[entries.length - 1];
+            if (!first || !last)
+                return;
+            checkAfterImports(last);
+            if (entries.length < 2)
+                return;
+            const rewrite = fixer => {
+                // Stable, so imports that share a group keep the order they were written in.
+                const sorted = [...entries].sort((a, b) => a.group - b.group);
+                let text = '';
+                let previous;
+                for (const entry of sorted) {
+                    if (previous) {
+                        const boundary = isLocalGroup(entry.group) !== isLocalGroup(previous.group);
+                        text += eol.repeat(boundary ? blankLines + 1 : 1);
+                    }
+                    text += source.text.slice(entry.start, entry.end);
+                    previous = entry;
+                }
+                return fixer.replaceTextRange([first.start, last.end], text);
+            };
+            let previousGroup = -1;
+            for (const entry of entries) {
+                if (entry.group < previousGroup) {
+                    context.report({
+                        node: entry.node,
+                        messageId: 'groupOrder',
+                        data: { group: nameOfGroup(entry.group), other: nameOfGroup(previousGroup) },
+                        fix: rewrite,
+                    });
+                    return;
+                }
+                previousGroup = entry.group;
+            }
+            for (let i = 1; i < entries.length; i++) {
+                const previous = entries[i - 1];
+                const entry = entries[i];
+                if (!previous || !entry)
+                    continue;
+                const gap = source.text.slice(previous.end, entry.start);
+                const blank = Math.max((gap.match(BREAK_GLOBAL) ?? []).length - 1, 0);
+                const boundary = isLocalGroup(entry.group) !== isLocalGroup(previous.group);
+                const wanted = boundary ? blankLines : 0;
+                if (blank === wanted)
+                    continue;
+                if (boundary) {
+                    context.report({
+                        node: entry.node,
+                        messageId: 'blankLines',
+                        data: { expected: String(wanted), actual: String(blank), lines: wanted === 1 ? 'line' : 'lines' },
+                        fix: rewrite,
+                    });
+                }
+                else {
+                    context.report({ node: entry.node, messageId: 'unexpectedBlankLine', fix: rewrite });
+                }
+                return;
+            }
+        };
+        return {
+            ImportDeclaration: checkSpecifiers,
+            'Program:exit'(program) {
+                let chunk = [];
+                const flush = () => {
+                    if (chunk.length > 0)
+                        checkChunk(chunk);
+                    chunk = [];
+                };
+                for (const statement of program.body) {
+                    // A bare `import 'x'` sorts like any other — where its side effect has to run in a
+                    // particular place, that is what a disable comment is for. Anything that is not an
+                    // import does end the run, since moving code across it could change what happens.
+                    if (statement.type === 'ImportDeclaration')
+                        chunk.push(statement);
+                    else
+                        flush();
+                }
+                flush();
+            },
+        };
+    },
+};
+export default rule;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "eslint-plugin-imports-regulation",
+  "version": "0.1.0",
+  "description": "Order imports: package type-only, package, blank line, local type-only, local — with type specifiers last inside each import.",
+  "author": "Robert Sandiford",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "typescript",
+    "import",
+    "import-order"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "@typescript-eslint/utils": "^8.67.0"
+  },
+  "peerDependencies": {
+    "eslint": "^9.39.4 || ^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "eslint": "^10.8.1",
+    "typescript-eslint": "^8.67.0"
+  },
+  "scripts": {
+    "compile": "tsc",
+    "build": "tsc --watch",
+    "test": "node --test --watch \"dist/**/*.test.js\"",
+    "test-once": "tsc && node --test \"dist/**/*.test.js\"",
+    "release": "node ../../scripts/release-package.ts"
+  }
+}