@noxickon/codex 1.3.0 → 1.4.0

package/eslint/base.config.js

@@ -19,6 +19,8 @@ import unusedImports from 'eslint-plugin-unused-imports';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
 
+import { codexPlugin } from './plugin.js';
+
 export function createBaseConfig(options = {}) {
   const { tailwindEntryPoint = './src/tailwind.css', enableTailwind = true } = options;
 
@@ -52,12 +54,16 @@ export function createBaseConfig(options = {}) {
         globals: globals.browser,
       },
       plugins: {
+        '@noxickon': codexPlugin,
         perfectionist,
         'sort-destructure-keys': sortDestructureKeys,
         unicorn,
         'unused-imports': unusedImports,
       },
       rules: {
+        // Blank-line spacing - direction-aware blank lines between statements
+        '@noxickon/blank-line-spacing': 'warn',
+
         // Unicorn - modern JS/TS best practices
         ...unicorn.configs.recommended.rules,
 

package/eslint/css.config.js

@@ -0,0 +1,25 @@
+/**
+ * CSS ESLint configuration (stripped-down blank-line spacing).
+ * Requires the optional peer dependency `@eslint/css`.
+ * @returns {Array} ESLint flat config array
+ */
+
+import css from '@eslint/css';
+
+import { codexPlugin } from './plugin.js';
+
+export function createCssConfig() {
+  return [
+    {
+      files: ['**/*.css'],
+      language: 'css/css',
+      plugins: {
+        css,
+        '@noxickon': codexPlugin,
+      },
+      rules: {
+        '@noxickon/blank-line-spacing-css': 'warn',
+      },
+    },
+  ];
+}

package/eslint/html.config.js

@@ -0,0 +1,26 @@
+/**
+ * HTML ESLint configuration (blank-line spacing for elements).
+ * Requires the optional peer dependency `@html-eslint/parser`.
+ * @returns {Array} ESLint flat config array
+ */
+
+import htmlParser from '@html-eslint/parser';
+
+import { codexPlugin } from './plugin.js';
+
+export function createHtmlConfig() {
+  return [
+    {
+      files: ['**/*.html'],
+      languageOptions: {
+        parser: htmlParser,
+      },
+      plugins: {
+        '@noxickon': codexPlugin,
+      },
+      rules: {
+        '@noxickon/blank-line-spacing-html': 'warn',
+      },
+    },
+  ];
+}

package/eslint/plugin.js

@@ -0,0 +1,15 @@
+import blankLineSpacing from './rules/blank-line-spacing.js';
+import blankLineSpacingCss from './rules/blank-line-spacing-css.js';
+import blankLineSpacingHtml from './rules/blank-line-spacing-html.js';
+
+export const codexPlugin = {
+  meta: {
+    name: '@noxickon/codex',
+    version: '1.3.1',
+  },
+  rules: {
+    'blank-line-spacing': blankLineSpacing,
+    'blank-line-spacing-html': blankLineSpacingHtml,
+    'blank-line-spacing-css': blankLineSpacingCss,
+  },
+};

package/eslint/rules/blank-line-spacing-css.js

@@ -0,0 +1,51 @@
+/**
+ * Stripped-down blank-line rule for CSS (H1): after a multiline block
+ * (`{ ... }` spanning multiple lines), require one blank line before the
+ * next rule/at-rule. Declarations inside a block are not touched (H2).
+ * Requires the optional peer dependency `@eslint/css`.
+ */
+
+export default {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Require a blank line after a multiline CSS block',
+    },
+    fixable: 'whitespace',
+    schema: [],
+    messages: {
+      expected: 'Expected a blank line after the previous block.',
+    },
+  },
+  create(context) {
+    function process(children) {
+      for (let i = 1; i < children.length; i += 1) {
+        const prev = children[i - 1];
+        const curr = children[i];
+
+        if (prev.loc.start.line === prev.loc.end.line) {
+          continue;
+        }
+
+        if (curr.loc.start.line - prev.loc.end.line - 1 < 1) {
+          const end = prev.loc.end.offset;
+
+          context.report({
+            loc: curr.loc.start,
+            messageId: 'expected',
+            fix: (fixer) => fixer.insertTextAfterRange([end, end], '\n'),
+          });
+        }
+      }
+    }
+
+    return {
+      StyleSheet: (node) => process(node.children),
+      Atrule: (node) => {
+        if (node.block && node.block.children) {
+          process(node.block.children);
+        }
+      },
+    };
+  },
+};

package/eslint/rules/blank-line-spacing-html.js

@@ -0,0 +1,38 @@
+/**
+ * Enforces direction-aware blank lines between HTML elements (Tag nodes).
+ * Mirrors the element matrix used for JSX/Vue templates:
+ *   single el -> single el : no blank
+ *   single el -> multiline el (lone) : no blank
+ *   multiline el -> el : blank
+ *   group(2+ singles) -> multiline el : blank
+ * Requires the optional peer dependency `@html-eslint/parser`.
+ */
+
+import { processElementChildren } from './shared.js';
+
+const HTML_ELEMENT_TYPES = new Set(['Tag']);
+
+export default {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Enforce direction-aware blank lines between HTML elements',
+    },
+    fixable: 'whitespace',
+    schema: [],
+    messages: {
+      expected: 'Expected a blank line before this element.',
+      unexpected: 'Unexpected blank line before this element.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+    const process = (children) =>
+      processElementChildren(context, sourceCode, children, HTML_ELEMENT_TYPES, 'Text', (node) => node.range);
+
+    return {
+      Document: (node) => process(node.children),
+      Tag: (node) => process(node.children),
+    };
+  },
+};

package/eslint/rules/blank-line-spacing.js

@@ -0,0 +1,254 @@
+/**
+ * Enforces direction-aware blank lines between statements.
+ *
+ * Matrix (single = one source line, multiline = spans multiple lines):
+ *   single   -> single    : no blank        (M1)
+ *   single   -> multiline : no blank        (M2, "lone setup line")
+ *   multiline-> single    : blank required   (M3)
+ *   multiline-> multiline : blank required   (M4)
+ *   group(2+ singles) -> multiline : blank required (M5)
+ *
+ * Extra rules:
+ *   - Block G: in a block of >= 3 statements, a blank is required before a
+ *     trailing single-line exit (return/throw/break/continue).
+ *   - N1: function/class/top-level declarations always get a blank before them
+ *     (M2 "no blank" applies only to control-flow/expression blocks).
+ *   - N2a: blanks that violate "no blank" are removed (normalisation).
+ *   - N2b: a single blank directly above a leading comment is preserved.
+ *   - D4: import statements and re-export lists are left untouched.
+ */
+
+import { processElementChildren } from './shared.js';
+
+const EXIT_TYPES = new Set(['ReturnStatement', 'ThrowStatement', 'BreakStatement', 'ContinueStatement']);
+const FUNCTION_INIT_TYPES = new Set(['ArrowFunctionExpression', 'FunctionExpression', 'ClassExpression']);
+const JSX_ELEMENT_TYPES = new Set(['JSXElement', 'JSXFragment']);
+const VUE_ELEMENT_TYPES = new Set(['VElement']);
+
+function isMultiline(node) {
+  return node.loc.start.line !== node.loc.end.line;
+}
+
+function isExit(node) {
+  return EXIT_TYPES.has(node.type);
+}
+
+function isSkipped(node) {
+  if (node.type === 'ImportDeclaration' || node.type === 'ExportAllDeclaration') {
+    return true;
+  }
+
+  return node.type === 'ExportNamedDeclaration' && !node.declaration;
+}
+
+function isDefinitionLike(node) {
+  switch (node.type) {
+    case 'FunctionDeclaration':
+    case 'ClassDeclaration':
+    case 'TSInterfaceDeclaration':
+    case 'TSTypeAliasDeclaration':
+    case 'TSEnumDeclaration':
+    case 'TSModuleDeclaration':
+    case 'ExportDefaultDeclaration':
+      return true;
+    case 'ExportNamedDeclaration':
+      return Boolean(node.declaration);
+    case 'VariableDeclaration':
+      return node.declarations.some((d) => d.init && FUNCTION_INIT_TYPES.has(d.init.type));
+    default:
+      return false;
+  }
+}
+
+function caseIsMultiline(switchCase) {
+  const body = switchCase.consequent;
+
+  if (body.length === 0) {
+    return false;
+  }
+
+  if (body.length === 1) {
+    return isMultiline(body[0]);
+  }
+
+  return true;
+}
+
+function getActualLastToken(sourceCode, node) {
+  const last = sourceCode.getLastToken(node);
+
+  if (!last || last.type !== 'Punctuator' || last.value !== ';') {
+    return last;
+  }
+
+  const prevToken = sourceCode.getTokenBefore(last);
+  const nextToken = sourceCode.getTokenAfter(last);
+  const semicolonLess = Boolean(
+    prevToken &&
+      nextToken &&
+      prevToken.range[0] >= node.range[0] &&
+      last.loc.start.line !== prevToken.loc.end.line &&
+      last.loc.end.line === nextToken.loc.start.line,
+  );
+
+  return semicolonLess ? prevToken : last;
+}
+
+export default {
+  meta: {
+    type: 'layout',
+    docs: {
+      description: 'Enforce direction-aware blank lines between statements',
+    },
+    fixable: 'whitespace',
+    schema: [],
+    messages: {
+      expected: 'Expected a blank line before this statement.',
+      unexpected: 'Unexpected blank line before this statement.',
+    },
+  },
+  create(context) {
+    const sourceCode = context.sourceCode;
+
+    function leadingComments(prevAnchor, node) {
+      return sourceCode
+        .getCommentsBefore(node)
+        .filter((comment) => comment.loc.start.line !== prevAnchor.loc.end.line);
+    }
+
+    function trailingAnchor(prevNode) {
+      const lastToken = getActualLastToken(sourceCode, prevNode);
+      const trailing = sourceCode
+        .getCommentsAfter(lastToken)
+        .filter((comment) => comment.loc.start.line === lastToken.loc.end.line);
+
+      return trailing.length > 0 ? trailing.at(-1) : lastToken;
+    }
+
+    function blankCountBetween(prevNode, node) {
+      const anchor = trailingAnchor(prevNode);
+      const comments = leadingComments(anchor, node);
+      const start = comments.length > 0 ? comments[0] : sourceCode.getFirstToken(node);
+
+      return start.loc.start.line - anchor.loc.end.line - 1;
+    }
+
+    function isGroupedSingle(prevPrev, prev, multilineOf) {
+      if (!prevPrev || isSkipped(prevPrev) || multilineOf(prevPrev)) {
+        return false;
+      }
+
+      return blankCountBetween(prevPrev, prev) === 0;
+    }
+
+    function needsBlank({ prevPrev, prev, curr, isLast, listLength, kind }) {
+      const multilineOf = kind === 'switch' ? caseIsMultiline : isMultiline;
+      const prevMulti = multilineOf(prev);
+      const currMulti = multilineOf(curr);
+
+      if (currMulti) {
+        if (kind === 'statement' && isDefinitionLike(curr)) {
+          return true;
+        }
+
+        if (prevMulti) {
+          return true;
+        }
+
+        return isGroupedSingle(prevPrev, prev, multilineOf);
+      }
+
+      if (prevMulti) {
+        return true;
+      }
+
+      return kind === 'statement' && isLast && listLength >= 3 && isExit(curr);
+    }
+
+    function checkPair(prev, curr, needBlank) {
+      const anchor = trailingAnchor(prev);
+      const comments = leadingComments(anchor, curr);
+      const start = comments.length > 0 ? comments[0] : sourceCode.getFirstToken(curr);
+      const blankCount = start.loc.start.line - anchor.loc.end.line - 1;
+
+      if (needBlank && blankCount < 1) {
+        context.report({
+          node: curr,
+          loc: start.loc,
+          messageId: 'expected',
+          fix: (fixer) => fixer.insertTextAfter(anchor, '\n'),
+        });
+
+        return;
+      }
+
+      if (!needBlank && blankCount > 0) {
+        if (comments.length > 0) {
+          return;
+        }
+
+        const between = sourceCode.text.slice(anchor.range[1], start.range[0]);
+        const indent = between.slice(between.lastIndexOf('\n') + 1);
+
+        context.report({
+          node: curr,
+          loc: start.loc,
+          messageId: 'unexpected',
+          fix: (fixer) => fixer.replaceTextRange([anchor.range[1], start.range[0]], `\n${indent}`),
+        });
+      }
+    }
+
+    function processList(list, kind = 'statement') {
+      for (let i = 1; i < list.length; i += 1) {
+        const prev = list[i - 1];
+        const curr = list[i];
+
+        if (isSkipped(prev) || isSkipped(curr)) {
+          continue;
+        }
+
+        const needBlank = needsBlank({
+          prevPrev: list[i - 2],
+          prev,
+          curr,
+          isLast: i === list.length - 1,
+          listLength: list.length,
+          kind,
+        });
+
+        checkPair(prev, curr, needBlank);
+      }
+    }
+
+    const rangeOf = (node) => node.range;
+    const processJsx = (children) =>
+      processElementChildren(context, sourceCode, children, JSX_ELEMENT_TYPES, 'JSXText', rangeOf);
+
+    const scriptVisitors = {
+      Program: (node) => processList(node.body),
+      BlockStatement: (node) => processList(node.body),
+      StaticBlock: (node) => processList(node.body),
+      SwitchCase: (node) => processList(node.consequent),
+      SwitchStatement: (node) => processList(node.cases, 'switch'),
+      ClassBody: (node) => processList(node.body),
+      TSModuleBlock: (node) => processList(node.body),
+      JSXElement: (node) => processJsx(node.children),
+      JSXFragment: (node) => processJsx(node.children),
+    };
+
+    const services = sourceCode.parserServices;
+
+    if (services && typeof services.defineTemplateBodyVisitor === 'function') {
+      return services.defineTemplateBodyVisitor(
+        {
+          VElement: (node) =>
+            processElementChildren(context, sourceCode, node.children, VUE_ELEMENT_TYPES, 'VText', rangeOf),
+        },
+        scriptVisitors,
+      );
+    }
+
+    return scriptVisitors;
+  },
+};

package/eslint/rules/blank-line-spacing.test.js

@@ -0,0 +1,272 @@
+import { RuleTester } from 'eslint';
+import { describe, it } from 'node:test';
+import tseslint from 'typescript-eslint';
+
+import rule from './blank-line-spacing.js';
+
+RuleTester.describe = describe;
+RuleTester.it = it;
+
+const js = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    parserOptions: { ecmaFeatures: { jsx: true } },
+  },
+});
+
+const ts = new RuleTester({
+  languageOptions: {
+    parser: tseslint.parser,
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+  },
+});
+
+js.run('blank-line-spacing', rule, {
+  valid: [
+    // M1: single -> single grouped
+    'const a = 1;\nconst b = 2;\nconst c = 3;',
+
+    // M2: lone setup -> multiline
+    'const userId = getId();\nif (userId === null) {\n  fail();\n}',
+
+    // M3: multiline -> single
+    'if (x) {\n  go();\n}\n\nconst y = 1;',
+
+    // M4: multiline -> multiline
+    'if (x) {\n  go();\n}\n\nfor (const i of list) {\n  use(i);\n}',
+
+    // M5: group of singles -> multiline
+    'const a = 1;\nconst b = 2;\n\nif (a + b > 0) {\n  go();\n}',
+
+    // Block G: <= 2 statements stay tight
+    'function f() {\n  doIt();\n  return true;\n}',
+
+    // Block G: >= 3 statements -> blank before exit
+    'function f() {\n  a();\n  b();\n\n  return true;\n}',
+
+    // Block G with throw
+    'function f() {\n  const x = a();\n  const y = b();\n\n  throw new Error(x + y);\n}',
+
+    // N1: function declaration always gets a blank before it
+    'const max = 10;\n\nfunction make() {\n  return max;\n}',
+
+    // N2b: blank above a comment is preserved (section divider)
+    'const config = load();\n\n// SECTION\nconst valid = config.ok;',
+
+    // comment does not break a group (no blank) -> group still needs blank before block
+    'const a = 1;\n// explains b\nconst b = 2;\n\nif (a + b) {\n  go();\n}',
+
+    // imports untouched (perfectionist owns them)
+    "import a from 'a';\n\nimport b from 'b';\nconst x = 1;",
+
+    // class: fields grouped, blank before method
+    'class C {\n  a = 1;\n  b = 2;\n\n  run() {\n    go();\n  }\n}',
+
+    // switch: single-line cases grouped, multiline case separated
+    'function pick(t) {\n  switch (t) {\n    case 1:\n      return a();\n    case 2:\n      return b();\n\n    case 3: {\n      const x = c();\n      return x;\n    }\n\n    default:\n      return d();\n  }\n}',
+
+    // multiline before exit already separated by M3, no extra blank
+    'function f() {\n  if (a) {\n    return 0;\n  }\n\n  return 1;\n}',
+
+    // JSX: single-line sibling elements grouped
+    'const x = (\n  <div>\n    <span>a</span>\n    <span>b</span>\n  </div>\n);',
+
+    // JSX: lone single element -> multiline element = no blank (T4/M2)
+    'const x = (\n  <div>\n    <span>a</span>\n    <ul>\n      <li>b</li>\n    </ul>\n  </div>\n);',
+
+    // JSX: multiline element -> following element = blank (T3)
+    'const x = (\n  <div>\n    <ul>\n      <li>a</li>\n    </ul>\n\n    <span>b</span>\n  </div>\n);',
+
+    // JSX: group of single elements -> multiline element = blank
+    'const x = (\n  <div>\n    <span>a</span>\n    <span>b</span>\n\n    <form>\n      <input />\n    </form>\n  </div>\n);',
+  ],
+  invalid: [
+    // M1 violation: stray blank between singles -> removed
+    {
+      code: 'const a = 1;\n\nconst b = 2;',
+      output: 'const a = 1;\nconst b = 2;',
+      errors: [{ messageId: 'unexpected' }],
+    },
+
+    // M2 violation: lone setup -> multiline should not have blank
+    {
+      code: 'const x = get();\n\nif (x) {\n  go();\n}',
+      output: 'const x = get();\nif (x) {\n  go();\n}',
+      errors: [{ messageId: 'unexpected' }],
+    },
+
+    // M3 violation: multiline -> single missing blank
+    {
+      code: 'if (x) {\n  go();\n}\nconst y = 1;',
+      output: 'if (x) {\n  go();\n}\n\nconst y = 1;',
+      errors: [{ messageId: 'expected' }],
+    },
+
+    // M5 violation: group of singles -> multiline missing blank
+    {
+      code: 'const a = 1;\nconst b = 2;\nif (a + b) {\n  go();\n}',
+      output: 'const a = 1;\nconst b = 2;\n\nif (a + b) {\n  go();\n}',
+      errors: [{ messageId: 'expected' }],
+    },
+
+    // Block G: 3 statements, missing blank before return
+    {
+      code: 'function f() {\n  a();\n  b();\n  return true;\n}',
+      output: 'function f() {\n  a();\n  b();\n\n  return true;\n}',
+      errors: [{ messageId: 'expected' }],
+    },
+
+    // N1: missing blank before function declaration
+    {
+      code: 'const max = 10;\nfunction make() {\n  return max;\n}',
+      output: 'const max = 10;\n\nfunction make() {\n  return max;\n}',
+      errors: [{ messageId: 'expected' }],
+    },
+
+    // insert blank before a leading comment (blank goes above the comment)
+    {
+      code: 'if (x) {\n  go();\n}\n// note\nconst y = 1;',
+      output: 'if (x) {\n  go();\n}\n\n// note\nconst y = 1;',
+      errors: [{ messageId: 'expected' }],
+    },
+
+    // trailing comment on prev does not get split when inserting
+    {
+      code: 'const a = 1; // keep\nif (a) {\n  go();\n}\nconst b = 2;',
+      output: 'const a = 1; // keep\nif (a) {\n  go();\n}\n\nconst b = 2;',
+      errors: [{ messageId: 'expected' }],
+    },
+
+    // JSX: stray blank between single elements removed
+    {
+      code: 'const x = (\n  <div>\n    <span>a</span>\n\n    <span>b</span>\n  </div>\n);',
+      output: 'const x = (\n  <div>\n    <span>a</span>\n    <span>b</span>\n  </div>\n);',
+      errors: [{ messageId: 'unexpected' }],
+    },
+
+    // JSX: multiline element -> single element missing blank
+    {
+      code: 'const x = (\n  <div>\n    <ul>\n      <li>a</li>\n    </ul>\n    <span>b</span>\n  </div>\n);',
+      output: 'const x = (\n  <div>\n    <ul>\n      <li>a</li>\n    </ul>\n\n    <span>b</span>\n  </div>\n);',
+      errors: [{ messageId: 'expected' }],
+    },
+  ],
+});
+
+let vueParser;
+
+try {
+  vueParser = (await import('vue-eslint-parser')).default;
+} catch {
+  vueParser = null;
+}
+
+if (vueParser) {
+  const vue = new RuleTester({
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
+    },
+  });
+
+  vue.run('blank-line-spacing (vue)', rule, {
+    valid: [
+      // script grouped + blank before function; template grouped + blank before multiline
+      '<script setup>\nconst a = 1;\nconst b = 2;\n\nfunction go() {\n  a();\n}\n</script>\n\n<template>\n  <span>a</span>\n  <span>b</span>\n\n  <ul>\n    <li>x</li>\n  </ul>\n</template>\n',
+    ],
+    invalid: [
+      // template: stray blank between single elements removed
+      {
+        code: '<template>\n  <span>a</span>\n\n  <span>b</span>\n</template>\n',
+        output: '<template>\n  <span>a</span>\n  <span>b</span>\n</template>\n',
+        errors: [{ messageId: 'unexpected' }],
+      },
+
+      // template: group of single elements -> multiline element = blank
+      {
+        code: '<template>\n  <span>a</span>\n  <span>b</span>\n  <ul>\n    <li>x</li>\n  </ul>\n</template>\n',
+        output: '<template>\n  <span>a</span>\n  <span>b</span>\n\n  <ul>\n    <li>x</li>\n  </ul>\n</template>\n',
+        errors: [{ messageId: 'expected' }],
+      },
+    ],
+  });
+}
+
+let htmlParser;
+
+try {
+  htmlParser = (await import('@html-eslint/parser')).default;
+} catch {
+  htmlParser = null;
+}
+
+if (htmlParser) {
+  const htmlRule = (await import('./blank-line-spacing-html.js')).default;
+  const html = new RuleTester({ languageOptions: { parser: htmlParser } });
+
+  html.run('blank-line-spacing-html', htmlRule, {
+    valid: [
+      '<div>\n  <span>a</span>\n  <span>b</span>\n</div>\n',
+      '<div>\n  <ul>\n    <li>a</li>\n  </ul>\n\n  <span>b</span>\n</div>\n',
+    ],
+    invalid: [
+      {
+        code: '<div>\n  <span>a</span>\n\n  <span>b</span>\n</div>\n',
+        output: '<div>\n  <span>a</span>\n  <span>b</span>\n</div>\n',
+        errors: [{ messageId: 'unexpected' }],
+      },
+      {
+        code: '<div>\n  <ul>\n    <li>a</li>\n  </ul>\n  <span>b</span>\n</div>\n',
+        output: '<div>\n  <ul>\n    <li>a</li>\n  </ul>\n\n  <span>b</span>\n</div>\n',
+        errors: [{ messageId: 'expected' }],
+      },
+    ],
+  });
+}
+
+let cssPlugin;
+
+try {
+  cssPlugin = (await import('@eslint/css')).default;
+} catch {
+  cssPlugin = null;
+}
+
+if (cssPlugin) {
+  const cssRule = (await import('./blank-line-spacing-css.js')).default;
+  const cssTester = new RuleTester({ plugins: { css: cssPlugin }, language: 'css/css' });
+
+  cssTester.run('blank-line-spacing-css', cssRule, {
+    valid: [
+      '.a {\n  color: red;\n}\n\n.b {\n  color: blue;\n}\n',
+      '.a { color: red; }\n.b { color: blue; }\n',
+    ],
+    invalid: [
+      {
+        code: '.a {\n  color: red;\n}\n.b {\n  color: blue;\n}\n',
+        output: '.a {\n  color: red;\n}\n\n.b {\n  color: blue;\n}\n',
+        errors: [{ messageId: 'expected' }],
+      },
+    ],
+  });
+}
+
+ts.run('blank-line-spacing (ts)', rule, {
+  valid: [
+    // export const arrow = definition-like -> blank before it (present)
+    'const max = 10;\n\nexport const make = (): number => {\n  return max;\n};',
+
+    // interface members are not touched; blank after the interface (M3) is required
+    'interface User {\n  id: string;\n  name: string;\n}\n\nconst x = 1;',
+  ],
+  invalid: [
+    // missing blank before exported arrow declaration
+    {
+      code: 'const max = 10;\nexport const make = (): number => {\n  return max;\n};',
+      output: 'const max = 10;\n\nexport const make = (): number => {\n  return max;\n};',
+      errors: [{ messageId: 'expected' }],
+    },
+  ],
+});

package/eslint/rules/shared.js

@@ -0,0 +1,86 @@
+/**
+ * Shared element-spacing helpers used by the JSX/Vue, HTML rules.
+ * Works on any node that exposes `loc` (line info) and a pair of absolute
+ * text offsets via the `offsetsOf` accessor.
+ */
+
+function isMultilineNode(node) {
+  return node.loc.start.line !== node.loc.end.line;
+}
+
+export function elementNeedsBlank(prevPrev, prev, curr) {
+  const prevMulti = isMultilineNode(prev);
+  const currMulti = isMultilineNode(curr);
+
+  if (currMulti) {
+    if (prevMulti) {
+      return true;
+    }
+
+    return Boolean(
+      prevPrev && !isMultilineNode(prevPrev) && prev.loc.start.line - prevPrev.loc.end.line - 1 === 0,
+    );
+  }
+
+  return prevMulti;
+}
+
+export function reportElementPair(context, sourceCode, prev, curr, needBlank, offsetsOf) {
+  const prevEnd = offsetsOf(prev)[1];
+  const currStart = offsetsOf(curr)[0];
+  const blankCount = curr.loc.start.line - prev.loc.end.line - 1;
+
+  if (needBlank && blankCount < 1) {
+    context.report({
+      node: curr,
+      loc: curr.loc.start,
+      messageId: 'expected',
+      fix: (fixer) => fixer.insertTextAfterRange([prevEnd, prevEnd], '\n'),
+    });
+
+    return;
+  }
+
+  if (!needBlank && blankCount > 0) {
+    const between = sourceCode.text.slice(prevEnd, currStart);
+    const indent = between.slice(between.lastIndexOf('\n') + 1);
+
+    context.report({
+      node: curr,
+      loc: curr.loc.start,
+      messageId: 'unexpected',
+      fix: (fixer) => fixer.replaceTextRange([prevEnd, currStart], `\n${indent}`),
+    });
+  }
+}
+
+export function processElementChildren(context, sourceCode, children, elementTypes, textType, offsetsOf) {
+  let run = [];
+
+  const flush = () => {
+    for (let i = 1; i < run.length; i += 1) {
+      reportElementPair(
+        context,
+        sourceCode,
+        run[i - 1],
+        run[i],
+        elementNeedsBlank(run[i - 2], run[i - 1], run[i]),
+        offsetsOf,
+      );
+    }
+
+    run = [];
+  };
+
+  for (const child of children) {
+    if (elementTypes.has(child.type)) {
+      run.push(child);
+    } else if (child.type === textType && (child.value || '').trim() === '') {
+      continue;
+    } else {
+      flush();
+    }
+  }
+
+  flush();
+}

package/eslint/vue.config.js

@@ -0,0 +1,37 @@
+/**
+ * Vue ESLint configuration extending base config.
+ * Requires the optional peer dependency `vue-eslint-parser`.
+ * @param {Object} options - Configuration options
+ * @returns {Array} ESLint flat config array
+ */
+
+import tseslint from 'typescript-eslint';
+import vueParser from 'vue-eslint-parser';
+
+import { createBaseConfig } from './base.config.js';
+import { codexPlugin } from './plugin.js';
+
+export function createVueConfig(options = {}) {
+  const baseConfig = createBaseConfig(options);
+
+  const vueConfig = {
+    files: ['**/*.vue'],
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: {
+        parser: tseslint.parser,
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        extraFileExtensions: ['.vue'],
+      },
+    },
+    plugins: {
+      '@noxickon': codexPlugin,
+    },
+    rules: {
+      '@noxickon/blank-line-spacing': 'warn',
+    },
+  };
+
+  return [...baseConfig, vueConfig];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noxickon/codex",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "author": "noxickon",
   "license": "MIT",
   "description": "Shared ESLint & Prettier configuration for noxickon projects",
@@ -8,11 +8,22 @@
   "engines": {
     "node": ">=20.19.0"
   },
+  "scripts": {
+    "test": "node --test \"eslint/**/*.test.js\""
+  },
+  "devDependencies": {
+    "@eslint/css": ">=0.12.0",
+    "@html-eslint/parser": ">=0.62.0",
+    "vue-eslint-parser": ">=10.0.0"
+  },
   "exports": {
     "./prettier": "./prettier.config.js",
     "./eslint/base": "./eslint/base.config.js",
     "./eslint/node": "./eslint/node.config.js",
-    "./eslint/react": "./eslint/react.config.js"
+    "./eslint/react": "./eslint/react.config.js",
+    "./eslint/vue": "./eslint/vue.config.js",
+    "./eslint/html": "./eslint/html.config.js",
+    "./eslint/css": "./eslint/css.config.js"
   },
   "files": [
     "eslint",
@@ -41,12 +52,24 @@
     "globals": ">=17.1.0",
     "prettier": ">=3.8.1",
     "prettier-plugin-tailwindcss": ">=0.7.0",
-    "typescript-eslint": ">=8.57.0"
+    "typescript-eslint": ">=8.57.0",
+    "vue-eslint-parser": ">=10.0.0",
+    "@html-eslint/parser": ">=0.62.0",
+    "@eslint/css": ">=0.12.0"
   },
   "peerDependenciesMeta": {
     "eslint-plugin-better-tailwindcss": {
       "optional": true
     },
+    "vue-eslint-parser": {
+      "optional": true
+    },
+    "@html-eslint/parser": {
+      "optional": true
+    },
+    "@eslint/css": {
+      "optional": true
+    },
     "eslint-plugin-n": {
       "optional": true
     },