eslint-plugin-yenz 2.1.1 → 2.2.0-beta.1

package/README.md

@@ -73,7 +73,7 @@ type C = string | number | null | undefined
 
 Disallows `for`, `while`, and `do...while` loops. `for...of` and `for...in` are allowed.
 
-> **Note:** This rule is _not_ enabled in the `recommended` preset. Enable it explicitly or use the `all` preset.
+> **Note:** This rule is *not* enabled in the `recommended` preset. Enable it explicitly or use the `all` preset.
 
 **Bad:**
 
@@ -96,7 +96,7 @@ items.map(item => transform(item))
 
 Disallows arrow functions assigned to named variables. Prefer function declarations instead. Auto-fixable.
 
-> **Note:** This rule is _not_ enabled in the `recommended` preset. Enable it explicitly or use the `all` preset.
+> **Note:** This rule is *not* enabled in the `recommended` preset. Enable it explicitly or use the `all` preset.
 
 **Bad:**
 
@@ -123,8 +123,8 @@ class Foo { bar = () => {} }
 
 ## Preset Configurations
 
-- **`recommended`** - Enables `type-ordering` as error and `no-loops` as warning
-- **`all`** - Enables all rules (`type-ordering`, `no-loops`, `no-named-arrow-functions`) as errors
+- `**recommended**` - Enables `type-ordering` as error and `no-loops` as warning
+- `**all**` - Enables all rules (`type-ordering`, `no-loops`, `no-named-arrow-functions`) as errors
 
 # Release Procedure
 
@@ -134,20 +134,64 @@ class Foo { bar = () => {} }
 4. Add code samples in `test/` that intentionally fail your new or updated rules to confirm they are caught.
 5. Commit and push your changes, then open a PR.
 6. **Bump to a pre-release version and publish a beta:**
-   ```bash
+  ```bash
    yarn version --pre[major|minor|patch] --preid beta
    npm publish --tag beta                # or alpha, rc
-   ```
+  ```
    Users can test it with:
-   ```bash
-   yarn add eslint-plugin-yenz@beta   # or @alpha, @rc
-   ```
 7. After review, **merge your branch into `main`**.
 8. Open a version bump PR against `main` and merge it in.
-8. **Publish the stable release** from `main`:
-   ```bash
+9. **Publish the stable release** from `main`:
+  ```bash
    yarn version --[major|minor|patch]
    npm publish
-   ```
+  ```
 
 > **Why `yarn version` + `npm publish`?** `yarn version` handles the version bump, git tag, and commit. We use `npm publish` for the actual publish because `yarn publish` redundantly prompts for a new version even when one was already set.
+
+# Development
+- Use https://astexplorer.net/ to easily get the AST types for your changes
+
+## Adding tests
+
+Tests are fixture-based. All test cases live in a single file, `test/fixtures.ts`, and the runner (`test/run.js`) lints that file with ESLint, parses the JSON output, and compares it against inline annotations.
+
+### Annotations
+
+Each line in `test/fixtures.ts` may carry one or both of the following trailing comments:
+
+- `// expect-error <ruleId>` — the line must produce a violation reported by `<ruleId>` (e.g. `yenz/no-loops`).
+- `// fix: <expected-code>` — after running ESLint with `--fix-dry-run`, the line (with the `// expect-error ...` annotation stripped) must equal `<expected-code>`.
+
+Lines without `// expect-error` must produce **no** violations. Unexpected violations fail the test, just like missing ones.
+
+### Adding a positive case (rule should fire)
+
+Add a line that violates the rule and annotate it:
+
+```typescript
+const foo = () => {} // expect-error yenz/no-named-arrow-functions
+```
+
+If the rule is auto-fixable, also include the expected fixed output:
+
+```typescript
+const foo = () => {} // expect-error yenz/no-named-arrow-functions // fix: function foo() {}
+```
+
+### Adding a negative case (rule should not fire)
+
+Add the code with no annotation. A short `// Should pass:` comment above the block keeps the file readable:
+
+```typescript
+// Should pass:
+const arr = [1, 2, 3].map(x => x)
+```
+
+### Running tests
+
+```bash
+yarn test
+```
+
+The runner reports `Violations: X/Y passed` and `Fixes: X/Y passed`, and exits non-zero on any missing violation, unexpected violation, or fix mismatch.

package/index.js

@@ -1,12 +1,14 @@
 import typeOrdering from './lib/rules/type-ordering.js';
 import noLoops from './lib/rules/no-loops.js';
 import noNamedArrowFunctions from './lib/rules/no-named-arrow-functions.js';
+import exportAtEndOfFile from './lib/rules/export-at-end-of-file.js';
 
 const plugin = {
   rules: {
     'type-ordering': typeOrdering,
     'no-loops': noLoops,
     'no-named-arrow-functions': noNamedArrowFunctions,
+    'export-at-end-of-file': exportAtEndOfFile,
   },
 };
 

package/lib/rules/export-at-end-of-file.js

@@ -0,0 +1,229 @@
+// AST node types we treat as "exportable declarations" — i.e. things you can
+// inline-export with `export function`, `export class`, `export type`, or
+// `export interface`. The `TS*` types come from typescript-eslint and only
+// appear when the file is parsed with the TS parser.
+const EXPORTABLE_DECLARATION_TYPES = new Set([
+  'FunctionDeclaration',
+  'ClassDeclaration',
+  'TSTypeAliasDeclaration',
+  'TSInterfaceDeclaration',
+]);
+
+// Subset of the above that exists only at the type level. When listed at the
+// bottom of the file these need either `export type { … }` or per-name
+// `type` markers so tools like `verbatimModuleSyntax` keep them erased.
+const TYPE_ONLY_DECLARATION_TYPES = new Set([
+  'TSTypeAliasDeclaration',
+  'TSInterfaceDeclaration',
+]);
+
+/**
+ * Determines whether an AST node is an inline-exported declaration that this
+ * rule should flag. Matches statements like `export function foo() {}` or
+ * `export type Foo = …`, but ignores re-exports (`export { x } from '…'`)
+ * and bare specifier exports (`export { x }`).
+ *
+ * @param {object} node - Top-level program statement node.
+ * @returns {boolean} True when the node is an inline `export <decl>` form
+ *   covering function, class, type alias, or interface declarations.
+ */
+function isInlineExportableDeclaration(node) {
+  // `node.source` is non-null for re-exports (`export { x } from '…'`) and
+  // `node.declaration` is null for bare specifier exports (`export { x }`).
+  if (node.type !== 'ExportNamedDeclaration' || node.source || !node.declaration) {
+    return false;
+  }
+  const { declaration } = node;
+  // `declaration.id` is null for anonymous default-export-style declarations,
+  // which don't apply here but we guard against it for safety.
+  return EXPORTABLE_DECLARATION_TYPES.has(declaration.type) && Boolean(declaration.id);
+}
+
+/**
+ * Extracts the exported name (and whether it's type-only) from an inline
+ * export declaration so it can be appended to the consolidated export list.
+ *
+ * @param {object} exportNamedNode - An `ExportNamedDeclaration` node that
+ *   has already been validated by {@link isInlineExportableDeclaration}.
+ * @returns {{ name: string, isType: boolean }} Export item describing the
+ *   declared identifier and whether it should be marked `type` in the final
+ *   export statement.
+ */
+function getExportItem(exportNamedNode) {
+  const { declaration } = exportNamedNode;
+  return {
+    name: declaration.id.name,
+    isType: TYPE_ONLY_DECLARATION_TYPES.has(declaration.type),
+  };
+}
+
+/**
+ * Reads the items from an existing specifier-only export statement so they
+ * can be merged with the items we are about to append.
+ *
+ * Handles both forms of type-only exports:
+ *   - Statement-level: `export type { Foo, Bar }` → `exportNode.exportKind === 'type'`
+ *   - Per-specifier:   `export { type Foo, bar }` → `specifier.exportKind === 'type'`
+ *
+ * @param {object} exportNode - An `ExportNamedDeclaration` with no
+ *   `declaration` and no `source` (i.e. a bare `export { … }`).
+ * @returns {Array<{ name: string, isType: boolean }>} The specifier list
+ *   normalized into the same shape returned by {@link getExportItem}.
+ */
+function getSpecifierOnlyExportItems(exportNode) {
+  const items = [];
+  for (const specifier of exportNode.specifiers) {
+    // Skip `export { x as default }` (handled by ExportSpecifier with non-Identifier
+    // exported, e.g. StringLiteral) and any non-ExportSpecifier nodes a parser
+    // might produce.
+    if (specifier.type !== 'ExportSpecifier' || specifier.exported.type !== 'Identifier') {
+      continue;
+    }
+    const isType =
+      specifier.exportKind === 'type' ||
+      (exportNode.exportKind === 'type' && !exportNode.declaration);
+    items.push({ name: specifier.exported.name, isType });
+  }
+  return items;
+}
+
+/**
+ * Locates an existing bare `export { … }` / `export type { … }` statement at
+ * the program level so the autofix can merge new names into it instead of
+ * appending a second export block.
+ *
+ * @param {object} programNode - The top-level `Program` AST node.
+ * @returns {object | null} The matching `ExportNamedDeclaration`, or null
+ *   when no specifier-only export exists.
+ */
+function findSpecifierOnlyExport(programNode) {
+  const results = programNode.body.find(statement => statement.type === 'ExportNamedDeclaration'
+     && !statement.declaration && !statement.source && statement.specifiers.length > 0);
+  return results || null;
+}
+
+/**
+ * Combines existing export items with newly added ones, preserving order and
+ * dropping duplicates by name (existing wins, so an existing `type` marker
+ * isn't accidentally downgraded to a value export).
+ *
+ * @param {Array<{ name: string, isType: boolean }>} existingItems
+ * @param {Array<{ name: string, isType: boolean }>} addedItems
+ * @returns {Array<{ name: string, isType: boolean }>} Deduplicated, ordered
+ *   list of export items.
+ */
+function mergeExportItems(existingItems, addedItems) {
+  const seen = new Set();
+  const merged = [];
+  for (const item of existingItems) {
+    if (seen.has(item.name)) continue;
+    seen.add(item.name);
+    merged.push(item);
+  }
+  for (const item of addedItems) {
+    if (seen.has(item.name)) continue;
+    seen.add(item.name);
+    merged.push(item);
+  }
+  return merged;
+}
+
+/**
+ * Renders a list of export items as a single `export { … }` statement. When
+ * every item is type-only the output uses the statement-level `export type
+ * { … }` form; otherwise mixed lists use per-name `type` markers so type
+ * symbols stay erasable under `verbatimModuleSyntax`/isolated modules.
+ *
+ * @param {Array<{ name: string, isType: boolean }>} items
+ * @returns {string} A single-line export statement (no trailing newline).
+ */
+function formatMergedSpecifierExport(items) {
+  if (items.length === 0) {
+    return 'export {}';
+  }
+  if (items.every((item) => item.isType)) {
+    return `export type { ${items.map((item) => item.name).join(', ')} }`;
+  }
+  return `export { ${items
+    .map((item) => (item.isType ? `type ${item.name}` : item.name))
+    .join(', ')} }`;
+}
+
+const exportAtEndOfFileRule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Disallow inline export on function, class, type, or interface declarations; use a single export list at the end of the file',
+      recommended: false,
+    },
+    fixable: 'code',
+    schema: [],
+  },
+  create(context) {
+    const { sourceCode } = context;
+
+    return {
+      // Use `Program:exit` so we have the full body before deciding whether to
+      // merge into an existing trailing `export { … }`. We also attach the
+      // single, file-spanning autofix to the *last* violation only - ESLint
+      // applies fixes in document order, and reporting the same set of edits
+      // from every violation would race and produce overlapping fixes.
+      'Program:exit'(programNode) {
+        const violations = programNode.body.filter(isInlineExportableDeclaration);
+        if (violations.length === 0) {
+          return;
+        }
+
+        const addedExportItems = violations.map(getExportItem);
+        const lastViolation = violations[violations.length - 1];
+
+        violations.forEach((node) => {
+          context.report({
+            node,
+            message:
+              'Declare this without inline export and list it in a single export statement at the end of the file.',
+            ...(node === lastViolation
+              ? {
+                  fix(fixer) {
+                    // Strip the leading `export` from each violation by
+                    // replacing the whole `ExportNamedDeclaration` node with
+                    // the source text of its inner declaration.
+                    const edits = violations.map((exportNode) =>
+                      fixer.replaceText(exportNode, sourceCode.getText(exportNode.declaration))
+                    );
+
+                    const existingExport = findSpecifierOnlyExport(programNode);
+                    if (existingExport) {
+                      const merged = mergeExportItems(
+                        getSpecifierOnlyExportItems(existingExport),
+                        addedExportItems
+                      );
+                      edits.push(
+                        fixer.replaceText(existingExport, formatMergedSpecifierExport(merged))
+                      );
+                    } else {
+                      // No bare export to merge into - append a fresh one
+                      // after the program's last token. Ends with a newline to follow
+                      // best practices.
+                      const lastToken = sourceCode.getLastToken(programNode);
+                      edits.push(
+                        fixer.insertTextAfter(
+                          lastToken,
+                          `\n\n${formatMergedSpecifierExport(addedExportItems)}\n`
+                        )
+                      );
+                    }
+
+                    return edits;
+                  },
+                }
+              : {}),
+          });
+        });
+      },
+    };
+  },
+};
+
+export default exportAtEndOfFileRule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-yenz",
-  "version": "2.1.1",
+  "version": "2.2.0-beta.1",
   "description": "Adds custom rules that Jens likes",
   "repository": "https://github.com/JensAstrup/eslint-plugin-yenz",
   "type": "module",

package/test/eslint.config.js

@@ -14,6 +14,7 @@ export default [
       'yenz/type-ordering': 'error',
       'yenz/no-loops': 'error',
       'yenz/no-named-arrow-functions': 'error',
+      'yenz/export-at-end-of-file': 'error',
     },
   },
 ];

package/test/fixtures.ts

@@ -29,7 +29,7 @@ const typedReturn = (x: number): number => x // expect-error yenz/no-named-arrow
 const asyncWithParams = async (x: number) => x // expect-error yenz/no-named-arrow-functions // fix: async function asyncWithParams(x: number) { return x; }
 let lv = () => {} // expect-error yenz/no-named-arrow-functions // fix: function lv() {}
 var vv = () => {} // expect-error yenz/no-named-arrow-functions // fix: function vv() {}
-export const exported = () => {} // expect-error yenz/no-named-arrow-functions // fix: export function exported() {}
+export const exported = () => {} // expect-error yenz/no-named-arrow-functions // fix: function exported() {}
 
 // Should pass:
 const arr2 = [1, 2, 3].map(x => x)
@@ -39,3 +39,11 @@ class MyClass {
 const obj2 = {
   method: () => {}
 }
+
+export function exportFunction() { return 1; } // expect-error yenz/export-at-end-of-file // fix: function exportFunction() { return 1; }
+
+export class ExportClass { method() { return 1; } } // expect-error yenz/export-at-end-of-file // fix: class ExportClass { method() { return 1; } }
+
+export type FixtureExportType = 1 // expect-error yenz/export-at-end-of-file // fix: type FixtureExportType = 1
+
+export interface FixtureExportIface { n: number } // expect-error yenz/export-at-end-of-file // fix: interface FixtureExportIface { n: number }