@naturalcycles/dev-lib 20.8.0 → 20.10.0

package/cfg/eslint-rules.js

@@ -503,14 +503,14 @@ export default {
     '@typescript-eslint/dot-notation': 0, // not always desireable
     '@typescript-eslint/consistent-indexed-object-style': 0, // Record looses the name of the key
     '@typescript-eslint/no-unsafe-enum-comparison': 0, // not practically helpful
-    // stylistic
-    '@stylistic/padding-line-between-statements': [
-      2,
-      { blankLine: 'always', prev: 'function', next: '*' },
-      { blankLine: 'always', prev: '*', next: 'function' },
-      { blankLine: 'always', prev: 'class', next: '*' },
-      { blankLine: 'always', prev: '*', next: 'class' },
-    ],
-    '@stylistic/lines-between-class-members': [2, 'always', { exceptAfterSingleLine: true }],
+    // stylistic - replaced by custom oxlint rules
+    // '@stylistic/padding-line-between-statements': [
+    //   2,
+    //   { blankLine: 'always', prev: 'function', next: '*' },
+    //   { blankLine: 'always', prev: '*', next: 'function' },
+    //   { blankLine: 'always', prev: 'class', next: '*' },
+    //   { blankLine: 'always', prev: '*', next: 'class' },
+    // ],
+    // '@stylistic/lines-between-class-members': [2, 'always', { exceptAfterSingleLine: true }],
   },
 }

package/cfg/eslint.config.js

@@ -13,7 +13,6 @@ import eslintPluginOxlint from 'eslint-plugin-oxlint'
 import eslintPluginVitest from '@vitest/eslint-plugin'
 import eslintPluginImportX from 'eslint-plugin-import-x'
 import eslintPluginSimpleImportSort from 'eslint-plugin-simple-import-sort'
-import eslintPluginStylistic from '@stylistic/eslint-plugin'
 import eslintRules from './eslint-rules.js'
 import eslintVueRules from './eslint-vue-rules.js'
 import eslintVitestRules from './eslint-vitest-rules.js'
@@ -106,7 +105,7 @@ function getConfig(tsconfigPath) {
       // 'unused-imports': require('eslint-plugin-unused-imports'), // disabled in favor of biome rules
       'simple-import-sort': eslintPluginSimpleImportSort,
       // jsdoc: eslintPluginJsdoc, // oxlint
-      '@stylistic': eslintPluginStylistic,
+      // '@stylistic': eslintPluginStylistic, // oxlint custom plugin
     },
     languageOptions: {
       ecmaVersion: 'latest',

package/cfg/oxlint-plugin-stylistic.mjs

@@ -0,0 +1,299 @@
+const BLANK_LINE_PATTERN = /(?:\r?\n)[ \t]*(?:\r?\n)/
+const FALLBACK_PADDING_OPTIONS = [
+  { blankLine: 'always', prev: 'function', next: '*' },
+  { blankLine: 'always', prev: '*', next: 'function' },
+  { blankLine: 'always', prev: 'class', next: '*' },
+  { blankLine: 'always', prev: '*', next: 'class' },
+]
+
+/**
+ * Utility that unwraps export declarations so the underlying declaration
+ * (function/class) can be inspected.
+ */
+function unwrapExported(node) {
+  if (!node) return null
+  if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration') {
+    return node.declaration || null
+  }
+  return node
+}
+
+function isFunctionLikeStatement(node) {
+  const inner = unwrapExported(node)
+  if (!inner) return false
+
+  return inner.type === 'FunctionDeclaration'
+}
+
+function isFunctionOverloadStatement(node) {
+  const inner = unwrapExported(node)
+  if (!inner) return false
+
+  return inner.type === 'TSDeclareFunction'
+}
+
+function isClassLikeStatement(node) {
+  const inner = unwrapExported(node)
+  if (!inner) return false
+
+  return inner.type === 'ClassDeclaration'
+}
+
+function describeStatement(node) {
+  if (!node) return 'statement'
+  if (isFunctionLikeStatement(node)) return 'function declaration'
+  if (isClassLikeStatement(node)) return 'class declaration'
+  return 'statement'
+}
+
+function isMethodOverload(node) {
+  if (!node) return false
+  if (node.type !== 'MethodDefinition' && node.type !== 'TSAbstractMethodDefinition') return false
+  return node.value && node.value.type === 'TSEmptyBodyFunctionExpression'
+}
+
+function hasBlankLineBetween(sourceCode, prevNode, nextNode) {
+  if (!prevNode || !nextNode) return false
+  if (!prevNode.range || !nextNode.range) return false
+  if (prevNode.range[1] >= nextNode.range[0]) return false
+
+  const between = sourceCode.text.slice(prevNode.range[1], nextNode.range[0])
+  return BLANK_LINE_PATTERN.test(between)
+}
+
+function insertBlankLineBeforeNext(fixer, sourceCode, prevNode, nextNode) {
+  if (!prevNode || !nextNode) return null
+  if (!prevNode.range || !nextNode.range) return null
+  if (prevNode.range[1] >= nextNode.range[0]) return null
+
+  const between = sourceCode.text.slice(prevNode.range[1], nextNode.range[0])
+  const hasLinebreak = /\r?\n/.test(between)
+  const linebreak = sourceCode.text.includes('\r\n') ? '\r\n' : '\n'
+  const text = hasLinebreak ? linebreak : linebreak + linebreak
+
+  return fixer.insertTextBeforeRange([nextNode.range[0], nextNode.range[0]], text)
+}
+
+function matchesSelector(selector, candidate) {
+  if (selector == null) return false
+  if (selector === '*') return true
+  if (Array.isArray(selector)) return selector.some(item => matchesSelector(item, candidate))
+  return selector === candidate
+}
+
+const paddingLineBetweenStatementsRule = {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Require a blank line between functions and classes and surrounding statements',
+    },
+    fixable: 'whitespace',
+    schema: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          blankLine: { enum: ['always'] },
+          prev: { anyOf: [{ enum: ['*', 'function', 'class'] }, { type: 'array' }] },
+          next: { anyOf: [{ enum: ['*', 'function', 'class'] }, { type: 'array' }] },
+        },
+        required: ['blankLine', 'prev', 'next'],
+        additionalProperties: false,
+      },
+    },
+    defaultOptions: [],
+    messages: {
+      expectedBlankLine: 'Expected blank line between {prev} and {next}.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode
+    const options =
+      Array.isArray(context.options) && context.options.length > 0
+        ? context.options
+        : FALLBACK_PADDING_OPTIONS
+
+    const requiresBlankLine = {
+      beforeFunction: false,
+      afterFunction: false,
+      beforeClass: false,
+      afterClass: false,
+    }
+
+    for (const option of options) {
+      if (!option || option.blankLine !== 'always') continue
+
+      if (matchesSelector(option.prev, 'function') && matchesSelector(option.next, '*')) {
+        requiresBlankLine.afterFunction = true
+      }
+      if (matchesSelector(option.prev, '*') && matchesSelector(option.next, 'function')) {
+        requiresBlankLine.beforeFunction = true
+      }
+      if (matchesSelector(option.prev, 'class') && matchesSelector(option.next, '*')) {
+        requiresBlankLine.afterClass = true
+      }
+      if (matchesSelector(option.prev, '*') && matchesSelector(option.next, 'class')) {
+        requiresBlankLine.beforeClass = true
+      }
+    }
+
+    const shouldCheckFunctions = requiresBlankLine.beforeFunction || requiresBlankLine.afterFunction
+    const shouldCheckClasses = requiresBlankLine.beforeClass || requiresBlankLine.afterClass
+
+    if (!shouldCheckFunctions && !shouldCheckClasses) {
+      // Nothing to enforce, bail early.
+      return {}
+    }
+
+    function needsBlankLine(prevNode, nextNode) {
+      if (shouldCheckFunctions) {
+        if (
+          requiresBlankLine.afterFunction &&
+          isFunctionLikeStatement(prevNode) &&
+          !isFunctionOverloadStatement(nextNode)
+        ) {
+          return true
+        }
+        if (
+          requiresBlankLine.beforeFunction &&
+          isFunctionLikeStatement(nextNode) &&
+          !isFunctionOverloadStatement(prevNode)
+        ) {
+          return true
+        }
+      }
+      if (shouldCheckClasses) {
+        if (requiresBlankLine.afterClass && isClassLikeStatement(prevNode)) return true
+        if (requiresBlankLine.beforeClass && isClassLikeStatement(nextNode)) return true
+      }
+      return false
+    }
+
+    function checkStatements(statements) {
+      if (!Array.isArray(statements) || statements.length < 2) return
+
+      for (let i = 1; i < statements.length; i += 1) {
+        const prevNode = statements[i - 1]
+        const nextNode = statements[i]
+
+        if (!prevNode || !nextNode) continue
+        if (!needsBlankLine(prevNode, nextNode)) continue
+        if (hasBlankLineBetween(sourceCode, prevNode, nextNode)) continue
+
+        context.report({
+          node: nextNode,
+          messageId: 'expectedBlankLine',
+          data: {
+            prev: describeStatement(prevNode),
+            next: describeStatement(nextNode),
+          },
+          fix(fixer) {
+            return insertBlankLineBeforeNext(fixer, sourceCode, prevNode, nextNode)
+          },
+        })
+      }
+    }
+
+    return {
+      Program(node) {
+        checkStatements(node.body)
+      },
+      BlockStatement(node) {
+        checkStatements(node.body)
+      },
+      StaticBlock(node) {
+        checkStatements(node.body)
+      },
+      SwitchCase(node) {
+        checkStatements(node.consequent)
+      },
+    }
+  },
+}
+
+function isSingleLine(node, sourceCode) {
+  if (!node || !node.range) return false
+  const start = sourceCode.getLocFromIndex(node.range[0])
+  const endIndex = node.range[1] > node.range[0] ? node.range[1] - 1 : node.range[1]
+  const end = sourceCode.getLocFromIndex(endIndex)
+  return start.line === end.line
+}
+
+const linesBetweenClassMembersRule = {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Require blank lines between class members',
+    },
+    fixable: 'whitespace',
+    schema: [
+      { enum: ['always'] },
+      {
+        type: 'object',
+        properties: {
+          exceptAfterSingleLine: { type: 'boolean' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    defaultOptions: ['always', { exceptAfterSingleLine: false }],
+    messages: {
+      expectedBlankLine: 'Expected blank line between class members.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode
+    const mode = context.options?.[0] || 'always'
+    const exceptAfterSingleLine =
+      context.options?.[1]?.exceptAfterSingleLine !== undefined
+        ? Boolean(context.options[1].exceptAfterSingleLine)
+        : true
+    const exceptAfterOverload = true
+
+    if (mode !== 'always') {
+      return {}
+    }
+
+    function checkClassBody(body) {
+      if (!Array.isArray(body) || body.length < 2) return
+
+      const members = exceptAfterOverload ? body.filter(member => !isMethodOverload(member)) : body
+      if (members.length < 2) return
+
+      for (let i = 1; i < members.length; i += 1) {
+        const prevElement = members[i - 1]
+        const nextElement = members[i]
+        if (!prevElement || !nextElement) continue
+
+        if (exceptAfterSingleLine && isSingleLine(prevElement, sourceCode)) continue
+        if (hasBlankLineBetween(sourceCode, prevElement, nextElement)) continue
+
+        context.report({
+          node: nextElement,
+          messageId: 'expectedBlankLine',
+          fix(fixer) {
+            return insertBlankLineBeforeNext(fixer, sourceCode, prevElement, nextElement)
+          },
+        })
+      }
+    }
+
+    return {
+      ClassBody(node) {
+        checkClassBody(node.body)
+      },
+    }
+  },
+}
+
+const stylisticPlugin = {
+  meta: {
+    name: '@stylistic',
+  },
+  rules: {
+    'padding-line-between-statements': paddingLineBetweenStatementsRule,
+    'lines-between-class-members': linesBetweenClassMembersRule,
+  },
+}
+
+export default stylisticPlugin

package/cfg/oxlint.config.json

@@ -11,7 +11,16 @@
     "promise",
     "vitest"
   ],
+  "jsPlugins": ["./oxlint-plugin-stylistic.mjs"],
   "rules": {
+    "@stylistic/padding-line-between-statements": [
+      2,
+      { "blankLine": "always", "prev": "function", "next": "*" },
+      { "blankLine": "always", "prev": "*", "next": "function" },
+      { "blankLine": "always", "prev": "class", "next": "*" },
+      { "blankLine": "always", "prev": "*", "next": "class" }
+    ],
+    "@stylistic/lines-between-class-members": [2, "always", { "exceptAfterSingleLine": true }],
     "no-this-alias": 0,
     "no-async-promise-executor": 0,
     "no-standalone-expect": 0,

package/cfg/tsconfig.src.json

@@ -9,7 +9,7 @@
     "baseUrl": "${configDir}/src",
     "outDir": "${configDir}/dist",
     // Target/module
-    "target": "es2023",
+    "target": "es2024",
     "lib": ["esnext"], // add "dom" if needed
     // module `nodenext` is a modern mode that auto-detects cjs/esm
     // it also defaults `esModuleInterop` and `allowSyntheticDefaultImports` to true

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/dev-lib",
   "type": "module",
-  "version": "20.8.0",
+  "version": "20.10.0",
   "dependencies": {
     "@biomejs/biome": "^2",
     "@commitlint/cli": "^20",
@@ -10,7 +10,6 @@
     "@inquirer/prompts": "^7",
     "@naturalcycles/js-lib": "^15",
     "@naturalcycles/nodejs-lib": "^15",
-    "@stylistic/eslint-plugin": "^5",
     "@vitest/coverage-v8": "^4",
     "@vitest/eslint-plugin": "^1",
     "eslint": "^9",
@@ -78,7 +77,7 @@
     "dev-lib": "dist/bin/dev-lib.js"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24.10.0"
   },
   "publishConfig": {
     "provenance": true,