eslint-plugin-imports-regulation 0.2.14 → 0.2.16

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

@@ -1,5 +1,5 @@
 import type { TSESLint } from '@typescript-eslint/utils';
-type MessageIds = 'groupOrder' | 'exportBlock' | 'blankLinesBetween' | 'unexpectedBlankLine' | 'blankLineBelowComment' | 'typeSpecifiersLast' | 'typeSpecifiersFirst' | 'markTypeOnly' | 'typeOnlyImport' | 'typeOnlySpecifier' | 'blankLinesAfter' | 'multilineBraces';
+type MessageIds = 'groupOrder' | 'exportBlock' | 'blankLinesBetween' | 'unexpectedBlankLine' | 'blankLineBelowComment' | 'typeSpecifiersLast' | 'typeSpecifiersFirst' | 'markTypeOnly' | 'typeOnlyImport' | 'typeOnlySpecifier' | 'blankLinesAfter' | 'multilineBraces' | 'codeAmongImports' | 'manageLineLength' | 'exportsBlockGap' | 'exportsBlockSpacing';
 type Origin = 'external' | 'internal';
 type Options = [
     {
@@ -14,6 +14,7 @@ type Options = [
         preferTypeDeclarations?: boolean;
         inferTypeOnlyImports?: boolean;
         maxLen?: number;
+        manageLineLength?: boolean;
     }?
 ];
 declare const rule: TSESLint.RuleModule<MessageIds, Options>;

package/dist/rules/imports-regulation.js

@@ -62,6 +62,9 @@ const rule = {
                     inferTypeOnlyImports: { type: 'boolean' },
                     // The longest line a fix may write when it gathers names; lines as written are left alone.
                     maxLen: { type: 'integer', minimum: 1 },
+                    // Reformat the names to fill each line up to `maxLen`, breaking up longer lines.
+                    // Off, and the lines are left as written.
+                    manageLineLength: { type: 'boolean' },
                 },
                 additionalProperties: false,
             },
@@ -78,6 +81,10 @@ const rule = {
             typeOnlyImport: 'Everything this imports is only used as a type — write `import type`.',
             typeOnlySpecifier: '`{{name}}` is only used as a type — mark it `type`.',
             blankLinesAfter: 'Expected {{expected}} blank {{lines}} after the imports, found {{actual}}.',
+            codeAmongImports: 'Expected no code among the imports.',
+            manageLineLength: 'Expected these names to fill the line, within {{maxLen}} characters.',
+            exportsBlockGap: 'Expected at most {{expected}} blank {{lines}} before the exports block, found {{actual}}.',
+            exportsBlockSpacing: 'Expected at most {{expected}} blank {{lines}} between the exports, found {{actual}}.',
             multilineBraces: 'Expected a multiline {{kind}} to end a line with `{` and start one with `}{{tail}}`.',
         },
     },
@@ -95,6 +102,7 @@ const rule = {
         const preferTypeDeclarations = options?.preferTypeDeclarations ?? true;
         const inferTypeOnlyImports = options?.inferTypeOnlyImports ?? true;
         const maxLen = options?.maxLen ?? DEFAULT_MAX_LEN;
+        const manageLineLength = options?.manageLineLength ?? true;
         const eol = BREAK.exec(source.text)?.[0] ?? '\n';
         const originOf = (path) => {
             for (const { test, group } of patterns)
@@ -398,30 +406,87 @@ const rule = {
             const values = specifiers.filter(specifier => !isTypeSpecifier(specifier));
             return [...pack(types, indent, values.length > 0 || trailingComma), ...pack(values, indent, trailingComma)];
         };
+        /** Whitespace runs closed up, so a statement spread over lines can be measured as one. */
+        const flattened = (text) => text.replace(/\s*(?:\r\n|\n|\r)\s*/g, ' ');
+        /**
+         * The names filled to `maxLen`: one line if the whole statement fits, else stacked.
+         *
+         * The whole statement, not the names alone, since what is owed is a line within the limit —
+         * and what sits outside the braces (`import type {`, `} from '…'`) is part of that line.
+         */
+        const checkPacking = (node, specifiers, open, close) => {
+            if (specifiers.length === 0)
+                return false;
+            const interior = [open.range[1], close.range[0]];
+            // Rebuilt from the specifiers alone, so a comment among them would be dropped; attributes
+            // bring braces of their own, which flattening would mangle.
+            if (source.getAllComments().some(c => c.range[0] >= interior[0] && c.range[1] <= interior[1]))
+                return false;
+            if (node.type === 'ImportDeclaration' && node.attributes.length > 0)
+                return false;
+            const base = /^[^\S\r\n]*/.exec(lineAt(node.loc.start.line - 1))?.[0] ?? '';
+            const prefix = flattened(source.text.slice(node.range[0], open.range[1]));
+            const suffix = flattened(source.text.slice(close.range[0], node.range[1]));
+            const ordered = [
+                ...specifiers.filter(specifier => !isTypeSpecifier(specifier)),
+                ...specifiers.filter(isTypeSpecifier),
+            ];
+            const names = ordered.map(specifier => source.getText(specifier)).join(', ');
+            const oneLine = `${base}${prefix} ${names} ${suffix}`;
+            let wanted;
+            if (oneLine.length <= maxLen)
+                wanted = oneLine;
+            else {
+                const { indent } = source.text.slice(...interior).includes(eol)
+                    ? shapeOf(interior, specifiers)
+                    : { indent: `${base}    ` };
+                const lines = stacked(specifiers, indent, true);
+                wanted = `${base}${prefix}${eol}${lines.join(eol)}${eol}${base}${suffix}`;
+                // Breaking up a single line that is over the limit whatever is done to it gains nothing,
+                // and would be reported for ever. Filling lines makes them longer, which is the point.
+                const longest = (text) => Math.max(...text.split(BREAK_GLOBAL).map(line => line.length));
+                const written = `${base}${source.getText(node)}`;
+                if (!BREAK.test(written) && longest(wanted) >= longest(written))
+                    return false;
+            }
+            const current = `${base}${source.getText(node)}`;
+            if (wanted === current)
+                return false;
+            context.report({
+                node,
+                messageId: 'manageLineLength',
+                data: { maxLen: String(maxLen) },
+                fix: fixer => fixer.replaceTextRange(node.range, wanted.slice(base.length)),
+            });
+            return true;
+        };
+        /** Whether it reported the layout, which leaves the order and shape checks nothing to say. */
         const checkBraces = (node, specifiers) => {
             const first = specifiers[0];
             const last = specifiers[specifiers.length - 1];
             if (!first || !last)
-                return;
+                return false;
             const open = source.getTokenBefore(first, { filter: token => token.value === '{' });
             const close = source.getTokenAfter(last, { filter: token => token.value === '}' });
             if (!open || !close)
-                return;
+                return false;
+            if (manageLineLength && checkPacking(node, specifiers, open, close))
+                return true;
             // To the module, not the statement's end, so a multiline `with { … }` is not counted.
             const end = node.source ?? close;
             if (node.loc.start.line === end.loc.end.line)
-                return;
+                return false;
             const afterOpen = source.getTokenAfter(open, { includeComments: true });
             const beforeClose = source.getTokenBefore(close, { includeComments: true });
             const afterClose = source.getTokenAfter(close, { includeComments: true });
             if (!afterOpen || !beforeClose)
-                return;
+                return false;
             const openOk = afterOpen.loc.start.line > open.loc.end.line || afterOpen.type === 'Line';
             const closeOk = beforeClose.loc.end.line < close.loc.start.line;
             const from = node.source && afterClose?.value === 'from' ? afterClose : undefined;
             const fromOk = !from || from.loc.start.line === close.loc.end.line;
             if (openOk && closeOk && fromOk)
-                return;
+                return false;
             const base = /^[^\S\r\n]*/.exec(lineAt(node.loc.start.line - 1))?.[0] ?? '';
             let indent = `${base}    `;
             for (let line = node.loc.start.line; line < end.loc.end.line; line++) {
@@ -446,7 +511,22 @@ const rule = {
                     return fixes;
                 },
             });
+            return true;
         };
+        // Matched by its name after the plugin prefix, which differs by config.
+        const ruleName = context.id.split('/').pop() ?? context.id;
+        /** This rule is disabled on the statement's last line. */
+        const passedOver = (statement) => source.getCommentsAfter(statement).some(comment => {
+            if (comment.loc.start.line !== statement.loc.end.line)
+                return false;
+            const directive = /^eslint-disable-line(?:\s+([^]*?))?(?:\s--[^]*)?$/.exec(comment.value.trim());
+            if (!directive)
+                return false;
+            const rules = directive[1]?.split(',').map(rule => rule.trim()).filter(Boolean) ?? [];
+            return rules.length === 0 || rules.some(rule => rule === ruleName || rule.endsWith(`/${ruleName}`));
+        });
+        // Passed-over statements, by the header statement they follow and travel with.
+        const attached = new Map();
         /** `export … from` and `export { … }`, which sit among the imports; a declaration is code. */
         const isHeaderExport = (node) => node.type === 'ExportAllDeclaration' || (node.type === 'ExportNamedDeclaration' && node.declaration === null);
         /** Comments that mean something only where they are, so they never move with an import. */
@@ -494,9 +574,10 @@ const rule = {
                 }
                 // Every comment on the import's last line, not just the first: a second one there is
                 // not a note on the next import.
-                let end = node.range[1];
-                for (const comment of source.getCommentsAfter(node)) {
-                    if (comment.loc.start.line !== node.loc.end.line)
+                const tail = attached.get(node) ?? node;
+                let end = tail.range[1];
+                for (const comment of source.getCommentsAfter(tail)) {
+                    if (comment.loc.start.line !== tail.loc.end.line)
                         break;
                     end = comment.range[1];
                 }
@@ -624,6 +705,30 @@ const rule = {
             }
             const region = entries.slice(0, tail);
             const regionLast = region[region.length - 1] ?? last;
+            // The block is loose about what it holds, but one line separates it, or none at all if it
+            // is tucked against the imports.
+            const exportsGap = 1;
+            const closeGap = (above, here, blank, messageId) => {
+                context.report({
+                    node: here.node,
+                    messageId,
+                    data: {
+                        expected: String(exportsGap),
+                        actual: String(blank),
+                        lines: exportsGap === 1 ? 'line' : 'lines',
+                    },
+                    fix: fixer => fixer.replaceTextRange([above.end, here.start], eol.repeat(exportsGap + 1)),
+                });
+            };
+            for (let i = tail; i < entries.length; i++) {
+                const above = entries[i - 1];
+                const here = entries[i];
+                if (!above || !here)
+                    continue;
+                const blank = blankBetween(above, here);
+                if (blank > exportsGap)
+                    closeGap(above, here, blank, i === tail ? 'exportsBlockGap' : 'exportsBlockSpacing');
+            }
             // An unpaired export belongs with its module's imports; one with no module stays with its neighbour.
             const sited = new Set();
             for (const entry of region) {
@@ -765,7 +870,10 @@ const rule = {
         };
         return {
             ImportDeclaration(node) {
-                checkBraces(node, namedOf(node));
+                // A repacked import is rewritten whole, so the specifier checks would report the same
+                // thing twice; what is left of them lands on the next pass.
+                if (checkBraces(node, namedOf(node)))
+                    return;
                 checkSpecifiers(node);
             },
             ExportNamedDeclaration(node) {
@@ -779,14 +887,32 @@ const rule = {
                         checkChunk(chunk, chunk[0] === program.body[0]);
                     chunk = [];
                 };
-                for (const statement of program.body) {
+                const isHeader = (statement) => statement !== undefined && (statement.type === 'ImportDeclaration' || isHeaderExport(statement));
+                const body = program.body;
+                for (let i = 0; i < body.length; i++) {
+                    const statement = body[i];
                     // 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 or re-export does end the run, since moving code across it could change what happens.
-                    if (statement.type === 'ImportDeclaration' || isHeaderExport(statement))
+                    if (isHeader(statement)) {
                         chunk.push(statement);
-                    else
-                        flush();
+                        continue;
+                    }
+                    // Unless this rule is disabled on its line and imports carry on after it: then it goes with the import above.
+                    let j = i;
+                    for (let next = body[j]; next && !isHeader(next) && passedOver(next); next = body[j])
+                        j++;
+                    const above = chunk[chunk.length - 1];
+                    const last = body[j - 1];
+                    if (above && last && j > i && isHeader(body[j])) {
+                        attached.set(above, last);
+                        // Suppressed by the directive, and what keeps it in use: unused, `--fix` would delete it.
+                        for (const passed of body.slice(i, j))
+                            context.report({ node: passed, messageId: 'codeAmongImports' });
+                        i = j - 1;
+                        continue;
+                    }
+                    flush();
                 }
                 flush();
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-imports-regulation",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Order imports: external type-only, external, blank line, internal type-only, internal — with type specifiers last inside each import.",
   "author": "Robert Sandiford",
   "type": "module",