eslint-plugin-imports-regulation 0.2.9 → 0.2.11

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

@@ -1,5 +1,5 @@
 import type { TSESLint } from '@typescript-eslint/utils';
-type MessageIds = 'groupOrder' | 'blankLinesBetween' | 'unexpectedBlankLine' | 'blankLineBelowComment' | 'typeSpecifiersLast' | 'markTypeOnly' | 'typeOnlyImport' | 'typeOnlySpecifier' | 'blankLinesAfter';
+type MessageIds = 'groupOrder' | 'exportBlock' | 'blankLinesBetween' | 'unexpectedBlankLine' | 'blankLineBelowComment' | 'typeSpecifiersLast' | 'markTypeOnly' | 'typeOnlyImport' | 'typeOnlySpecifier' | 'blankLinesAfter';
 type Origin = 'external' | 'internal';
 type Options = [
     {

package/dist/rules/imports-regulation.js

@@ -64,6 +64,7 @@ const rule = {
         ],
         messages: {
             groupOrder: 'Expected this {{group}} import before the {{other}} imports.',
+            exportBlock: 'Expected this export from an {{origin}} module with the {{origin}} imports.',
             blankLinesBetween: 'Expected {{expected}} blank {{lines}} between external imports and internal imports, found {{actual}}.',
             unexpectedBlankLine: 'Expected no blank lines between imports in the same group, found {{actual}}.',
             blankLineBelowComment: 'Expected no blank lines between a comment and the import it belongs to, found {{actual}}.',
@@ -243,7 +244,9 @@ const rule = {
             for (const variable of source.getDeclaredVariables(node)) {
                 if (variable.references.length === 0)
                     continue;
-                if (variable.references.every(reference => reference.isTypeReference))
+                // A plain `export { x }` is flagged as both, and could be a value.
+                const typeOnly = variable.references.every(reference => reference.isTypeReference && !reference.isValueReference);
+                if (typeOnly)
                     names.add(variable.name);
             }
             return names;
@@ -335,6 +338,8 @@ const rule = {
                 fix: fixer => fixer.replaceTextRange(range, rejoin(range, named, [...values, ...types], specifier => source.getText(specifier))),
             });
         };
+        /** `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. */
         const staysPut = (comment) => {
             if (source.text.startsWith('#!', comment.range[0]))
@@ -386,8 +391,22 @@ const rule = {
                         break;
                     end = comment.range[1];
                 }
-                entries.push({ node, group: groupOf(node), start, end });
+                const isImport = node.type === 'ImportDeclaration';
+                entries.push({ node, isImport, group: isImport ? groupOf(node) : -1, start, end });
             }
+            // An export next to an import from the same module is bound to it, through any run of such exports.
+            const sourceOf = (entry) => entry?.node.source?.value;
+            const bind = (ordered) => {
+                for (const [i, entry] of ordered.entries()) {
+                    const neighbour = ordered[i - 1];
+                    if (entry.isImport || entry.group !== -1 || !neighbour || neighbour.group === -1)
+                        continue;
+                    if (sourceOf(entry) !== undefined && sourceOf(entry) === sourceOf(neighbour))
+                        entry.group = neighbour.group;
+                }
+            };
+            bind(entries);
+            bind([...entries].reverse());
             return entries;
         };
         /**
@@ -465,18 +484,58 @@ const rule = {
                 fix: fixer => fixer.replaceTextRange([from, to], eol.repeat(blankLinesAfter + 1)),
             });
         };
-        const checkChunk = (chunk) => {
+        const checkChunk = (chunk, leading) => {
             const entries = entriesOf(chunk);
             const first = entries[0];
             const last = entries[entries.length - 1];
             if (!first || !last)
                 return;
-            checkAfterImports(last);
+            // An import after code is not the imports block, so no gap is owed after it.
+            if (leading)
+                checkAfterImports(last);
             if (entries.length < 2)
                 return;
+            const blankBetween = (above, below) => {
+                const gap = source.text.slice(above.end, below.start);
+                return Math.max((gap.match(BREAK_GLOBAL) ?? []).length - 1, 0);
+            };
+            // Exports below every import, past a blank line, are a block of their own and left alone.
+            let lastImport = -1;
+            for (const [i, entry] of entries.entries())
+                if (entry.isImport)
+                    lastImport = i;
+            let tail = entries.length;
+            for (let i = lastImport + 1; i < entries.length; i++) {
+                const above = entries[i - 1];
+                const here = entries[i];
+                if (above && here && blankBetween(above, here) > 0) {
+                    tail = i;
+                    break;
+                }
+            }
+            const region = entries.slice(0, tail);
+            const regionLast = region[region.length - 1] ?? last;
+            // 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) {
+                if (entry.group !== -1 || entry.node.type === 'ImportDeclaration' || !entry.node.source)
+                    continue;
+                const base = originOf(entry.node.source.value) === 'internal' ? INTERNAL_TYPE : EXTERNAL_TYPE;
+                entry.group = entry.node.exportKind === 'type' ? base : base + 1;
+                sited.add(entry);
+            }
+            for (const ordered of [region, [...region].reverse()]) {
+                let neighbour = -1;
+                for (const entry of ordered) {
+                    if (entry.group === -1 && neighbour !== -1)
+                        entry.group = neighbour;
+                    if (entry.group !== -1)
+                        neighbour = entry.group;
+                }
+            }
             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);
+                const sorted = [...region].sort((a, b) => a.group - b.group);
                 let text = '';
                 let previous;
                 for (const entry of sorted) {
@@ -487,10 +546,12 @@ const rule = {
                     text += tightened(entry).text;
                     previous = entry;
                 }
-                return fixer.replaceTextRange([first.start, last.end], text);
+                return fixer.replaceTextRange([first.start, regionLast.end], text);
             };
             let previousGroup = -1;
             for (const entry of entries) {
+                if (!entry.isImport)
+                    continue;
                 if (entry.group < previousGroup) {
                     context.report({
                         node: entry.node,
@@ -502,14 +563,65 @@ const rule = {
                 }
                 previousGroup = entry.group;
             }
-            for (let i = 1; i < entries.length; i++) {
-                const previous = entries[i - 1];
+            // Blank lines split the region into paragraphs, and an export belongs to its paragraph's block.
+            const paragraphs = [];
+            for (const [i, entry] of region.entries()) {
+                const above = region[i - 1];
+                paragraphs.push(above ? (paragraphs[i - 1] ?? 0) + (blankBetween(above, entry) > 0 ? 1 : 0) : 0);
+            }
+            let misplaced = false;
+            for (const [i, entry] of region.entries()) {
+                if (!sited.has(entry))
+                    continue;
+                const internal = isInternalGroup(entry.group);
+                const nearest = (step, sameParagraph) => {
+                    for (let j = i + step; j >= 0 && j < region.length; j += step) {
+                        const other = region[j];
+                        if (other?.isImport && (!sameParagraph || paragraphs[j] === paragraphs[i]))
+                            return other;
+                    }
+                    return undefined;
+                };
+                const beside = nearest(-1, true) ?? nearest(1, true);
+                const above = nearest(-1, false);
+                const below = nearest(1, false);
+                // A paragraph of exports alone sits between blocks, and may belong to either; the top is external.
+                const fits = beside
+                    ? isInternalGroup(beside.group) === internal
+                    : (above !== undefined && isInternalGroup(above.group)) === internal
+                        || (below !== undefined && isInternalGroup(below.group) === internal);
+                if (fits)
+                    continue;
+                misplaced = true;
+                context.report({
+                    node: entry.node,
+                    messageId: 'exportBlock',
+                    data: { origin: internal ? 'internal' : 'external' },
+                    fix: rewrite,
+                });
+            }
+            if (misplaced)
+                return;
+            let previousIndex = entries.findIndex(entry => entry.isImport);
+            for (let i = previousIndex + 1; i < entries.length; i++) {
+                const previous = entries[previousIndex];
                 const entry = entries[i];
-                if (!previous || !entry)
+                if (!previous || !entry?.isImport)
                     continue;
-                const gap = source.text.slice(previous.end, entry.start);
-                const blank = Math.max((gap.match(BREAK_GLOBAL) ?? []).length - 1, 0);
+                const gaps = [];
+                for (let k = previousIndex + 1; k <= i; k++) {
+                    const above = entries[k - 1];
+                    const here = entries[k];
+                    if (above && here)
+                        gaps.push(blankBetween(above, here));
+                }
+                const acrossExports = i - previousIndex > 1;
+                previousIndex = i;
                 const boundary = isInternalGroup(entry.group) !== isInternalGroup(previous.group);
+                // Around exports the gaps are free, but the separation still has to fall somewhere in them.
+                if (acrossExports && !boundary)
+                    continue;
+                const blank = Math.max(...gaps);
                 const wanted = boundary ? blankLinesBetween : 0;
                 const below = tightened(entry).blank;
                 if (below > 0) {
@@ -547,15 +659,16 @@ const rule = {
             'Program:exit'(program) {
                 let chunk = [];
                 const flush = () => {
-                    if (chunk.length > 0)
-                        checkChunk(chunk);
+                    // Exports alone are not an imports block.
+                    if (chunk.some(node => node.type === 'ImportDeclaration'))
+                        checkChunk(chunk, chunk[0] === program.body[0]);
                     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')
+                    // import or re-export does end the run, since moving code across it could change what happens.
+                    if (statement.type === 'ImportDeclaration' || isHeaderExport(statement))
                         chunk.push(statement);
                     else
                         flush();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-imports-regulation",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "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",