@jmlweb/oxlint-config-node 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @jmlweb/oxlint-config-node
+
+## 0.1.0
+
+### Minor Changes
+
+- a32dbc9: Add `@jmlweb/oxlint-config-node`, an Oxlint configuration that extends `@jmlweb/oxlint-config-base` and ports `@jmlweb/eslint-config-node`. It runs `eslint-plugin-n`'s `flat/recommended` rules and the same best-practice rules as a JS plugin, uses Oxlint's native `node/*` rules where they exist, and sets Node.js globals for JavaScript and TypeScript files. The naming convention rule is not ported.

package/README.md

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+# @jmlweb/oxlint-config-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@jmlweb/oxlint-config-node)](https://www.npmjs.com/package/@jmlweb/oxlint-config-node)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.12.0-339933.svg)](https://nodejs.org/)
+
+> [Oxlint](https://oxc.rs/docs/guide/usage/linter.html) configuration for Node.js projects. Extends [`@jmlweb/oxlint-config-base`](../oxlint-config-base) and ports the rules of [`@jmlweb/eslint-config-node`](../eslint-config-node).
+
+## ✨ Features
+
+- 🟢 **eslint-plugin-n**: Its `flat/recommended` rules plus stricter best practices, run as an Oxlint JS plugin
+- ⚡ **Native where possible**: Rules Oxlint implements itself run natively instead of through the plugin
+- 📦 **Dependency checks**: Missing, extraneous and unpublished imports, resolved against your `package.json`
+- 🌐 **Node.js globals**: `process`, `Buffer`, `__dirname` and the rest, for JavaScript and TypeScript files
+- 🔒 **Everything from the base config**: Strict TypeScript rules, no enums, named exports only
+
+## 📦 Installation
+
+```bash
+pnpm add -D @jmlweb/oxlint-config-node oxlint oxlint-tsgolint eslint-plugin-n
+```
+
+## 🚀 Quick Start
+
+Create an `oxlint.config.ts` file in your project root:
+
+```typescript
+import nodeConfig from '@jmlweb/oxlint-config-node';
+import { defineConfig } from 'oxlint';
+
+export default defineConfig({
+  extends: [nodeConfig],
+  options: {
+    typeAware: true,
+  },
+});
+```
+
+> ⚠️ **`typeAware` must be set in your own config**: Oxlint only reads `options` from the root config file, so the base config's type-aware rules are skipped without it.
+
+## 💡 Examples
+
+### Before
+
+```typescript
+import fs from 'fs';
+import { parse } from 'yaml';
+
+export const loadConfig = (dir: string): unknown => {
+  const file = dir + '/config.yml';
+  if (!fs.existsSync(file)) {
+    process.exit(1);
+  }
+  fs.readFile(file, 'utf8', () => undefined);
+  return parse(fs.readFileSync(file, 'utf8'));
+};
+```
+
+### Problems Reported
+
+With `yaml` missing from `package.json`:
+
+```text
+src/config.ts:1:16: error n(prefer-node-protocol): Prefer `node:fs` over `fs`.
+src/config.ts:2:23: error n(no-missing-import): Can't resolve 'yaml' in '/path/to/project/src'
+src/config.ts:7:5: error n(no-process-exit): Don't use process.exit(); throw an error instead.
+src/config.ts:9:3: error n(prefer-promises/fs): Use 'fs.promises.readFile()' instead.
+src/config.ts:10:10: error typescript(no-unsafe-call): Unsafe call of a(n) `error` type typed value.
+```
+
+## 📋 Configuration Details
+
+### All Files
+
+- `eslint-plugin-n` `flat/recommended` rules: deprecated APIs, unsupported features for your `engines.node`, missing, extraneous and unpublished imports, hashbangs
+- Node.js globals for `**/*.{js,mjs,cjs,ts,mts,cts}`
+
+### Key Rules Enforced
+
+| Rule                      | Level   | Description                                         |
+| ------------------------- | ------- | --------------------------------------------------- |
+| `n/no-process-exit`       | `error` | Throw instead of calling `process.exit()`           |
+| `n/process-exit-as-throw` | `error` | Treats `process.exit()` as a throw for control flow |
+| `n/no-deprecated-api`     | `warn`  | Flags deprecated Node.js APIs                       |
+| `n/no-callback-literal`   | `error` | Callbacks receive an error or `null` first          |
+| `n/prefer-node-protocol`  | `error` | Use `node:` imports for built-in modules            |
+| `n/prefer-promises/fs`    | `error` | Use `fs.promises` over callback APIs                |
+| `n/prefer-promises/dns`   | `error` | Use `dns.promises` over callback APIs               |
+| `n/prefer-global/*`       | `error` | Use `Buffer`, `console`, `process`, `URL` globals   |
+| `node/no-new-require`     | `error` | Disallows `new require(...)`                        |
+| `node/no-path-concat`     | `error` | Use `path.join()` with `__dirname`/`__filename`     |
+| `node/no-exports-assign`  | `error` | Disallows assigning to `exports`                    |
+
+The `node/*` rules are Oxlint's native versions of the matching `n/*` rules.
+
+### Differences from `@jmlweb/eslint-config-node`
+
+- **No naming convention rule**: Same as [`@jmlweb/oxlint-config-base`](../oxlint-config-base#differences-from-jmlwebeslint-config-base)
+- **No import sorting rule**: [`@jmlweb/oxfmt-config-base`](../oxfmt-config-base) sorts imports
+
+## 🤔 Why Use This?
+
+> **Philosophy**: The Node.js rules of the ESLint config, run by Oxlint.
+
+### Design Decisions
+
+**eslint-plugin-n as a JS plugin**: Oxlint's native `node` plugin only covers a few of its rules
+
+- **Why**: Keeps the dependency checks and unsupported-feature rules, which have no native equivalent
+- **Trade-off**: Runs through Oxlint's JS plugin support, which is still in alpha
+- **When to override**: Turn off single `n/*` rules in your config
+
+**Node.js globals through an override**: The globals are set for JavaScript and TypeScript files instead of with a top-level `env`
+
+- **Why**: Oxlint ignores a top-level `env` in configs loaded through `extends`, but keeps it inside overrides
+- **Trade-off**: None
+- **When to override**: Not needed
+
+## 🎯 When to Use
+
+Use this package when you want:
+
+- ✅ Fast linting for Node.js libraries, CLIs and servers (recommended over ESLint)
+- ✅ Checks that every import is declared in `package.json`
+- ✅ To migrate from `@jmlweb/eslint-config-node`
+
+**For browser or React projects**, use [`@jmlweb/oxlint-config-base`](../oxlint-config-base) or [`@jmlweb/oxlint-config-react`](../oxlint-config-react) instead.
+
+## 🔧 Extending the Configuration
+
+```typescript
+import nodeConfig from '@jmlweb/oxlint-config-node';
+import { defineConfig } from 'oxlint';
+
+export default defineConfig({
+  extends: [nodeConfig],
+  options: {
+    typeAware: true,
+  },
+  overrides: [
+    {
+      // CLIs may exit with a status code
+      files: ['src/cli.ts'],
+      rules: {
+        'n/no-process-exit': 'off',
+      },
+    },
+    {
+      // Scripts and tests may import devDependencies
+      files: ['scripts/**', '**/*.test.ts'],
+      rules: {
+        'n/no-unpublished-import': 'off',
+      },
+    },
+  ],
+});
+```
+
+## 📝 Usage with Scripts
+
+Add linting scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix"
+  }
+}
+```
+
+Then run:
+
+```bash
+pnpm lint      # Lint all files
+pnpm lint:fix  # Fix auto-fixable problems
+```
+
+## 📋 Requirements
+
+- **Node.js** >= 22.12.0
+- **Oxlint** >= 1.87.0
+- **`engines.node`** in your `package.json` (used by the unsupported-feature rules)
+- **TypeScript project** with a `tsconfig.json` (for type-aware rules)
+
+## 📦 Peer Dependencies
+
+This package requires the following peer dependencies:
+
+- `oxlint` (>= 1.87.0)
+- `oxlint-tsgolint` (>= 7.0.0, optional, enables type-aware rules)
+- `eslint-plugin-n` (^17.0.0 || ^18.0.0)
+
+**Note**: `@jmlweb/oxlint-config-base` is a regular dependency, so you do not need to install it.
+
+## 📚 Examples
+
+See real-world usage examples:
+
+- [`@jmlweb/eslint-config-node`](../eslint-config-node) - The ESLint configuration this package ports
+
+## 🔗 Related Packages
+
+### Internal Packages
+
+- [`@jmlweb/oxlint-config-base`](../oxlint-config-base) - Base Oxlint config this package extends
+- [`@jmlweb/oxfmt-config-base`](../oxfmt-config-base) - Oxfmt config, the formatter to pair with this linter
+- [`@jmlweb/eslint-config-node`](../eslint-config-node) - ESLint equivalent of this configuration
+- [`@jmlweb/tsconfig-node`](../tsconfig-node) - TypeScript config for Node.js projects
+
+### External Tools
+
+- [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n) - Node.js rules run as a JS plugin
+- [Oxlint JS plugins](https://oxc.rs/docs/guide/usage/linter/js-plugins.html) - How Oxlint runs ESLint plugins
+
+## ⚠️ Common Issues
+
+> **Note:** This section documents known issues and their solutions. If you encounter a problem not listed here, please [open an issue](https://github.com/jmlweb/tooling/issues/new).
+
+### Unpublished Import Errors in Scripts or Tests
+
+**Symptoms:**
+
+- `n/no-unpublished-import` reports `devDependencies` imported from tests or scripts
+
+**Cause:**
+
+- The tests or scripts sit inside a folder listed in the `files` field of `package.json`, so they count as published code, which must not import `devDependencies`
+
+**Solution:**
+
+Turn the rule off for those files (see [Extending the Configuration](#-extending-the-configuration)), or make sure the `files` field only lists published code.
+
+### Oxlint Is Slow or Reports Problems in `node_modules`
+
+**Symptoms:**
+
+- Oxlint takes minutes or reports problems in dependencies
+
+**Cause:**
+
+- The project has no `.gitignore` listing `node_modules`, so Oxlint lints it
+
+**Solution:**
+
+Add `node_modules` to `.gitignore`, or to `ignorePatterns` in your Oxlint config.
+
+## 🔄 Migration Guide
+
+### Migrating from `@jmlweb/eslint-config-node`
+
+1. Install this package and its peer dependencies
+2. Create `oxlint.config.ts` as shown in [Quick Start](#-quick-start)
+3. Format with [`@jmlweb/oxfmt-config-base`](../oxfmt-config-base), which sorts imports
+4. Replace `eslint` with `oxlint` in your scripts and `lint-staged` config
+5. Remove `eslint.config.*` and the ESLint packages, except `eslint-plugin-n`
+6. Run `pnpm lint` and fix the reported problems
+
+### Upgrading to a New Version
+
+> **Note:** If no breaking changes were introduced in a version, it's safe to upgrade without additional steps.
+
+**No breaking changes have been introduced yet.** This package follows semantic versioning. When breaking changes are introduced, detailed migration instructions will be provided here.
+
+For version history, see the [Changelog](./CHANGELOG.md).
+
+**Need Help?** If you encounter issues during migration, please [open an issue](https://github.com/jmlweb/tooling/issues/new).
+
+## 📜 Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.
+
+## 📄 License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,93 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let _jmlweb_oxlint_config_base = require("@jmlweb/oxlint-config-base");
+_jmlweb_oxlint_config_base = __toESM(_jmlweb_oxlint_config_base, 1);
+let eslint_plugin_n = require("eslint-plugin-n");
+eslint_plugin_n = __toESM(eslint_plugin_n, 1);
+//#region src/index.ts
+/** Stricter or extra eslint-plugin-n rules, as in @jmlweb/eslint-config-node */
+const nodeBestPracticeRules = {
+	"n/no-process-exit": "error",
+	"n/no-missing-import": "error",
+	"n/no-missing-require": "error",
+	"n/no-unpublished-import": "error",
+	"n/no-unpublished-require": "error",
+	"n/no-extraneous-import": "error",
+	"n/no-extraneous-require": "error",
+	"n/no-deprecated-api": "warn",
+	"n/process-exit-as-throw": "error",
+	"n/no-callback-literal": "error",
+	"n/no-new-require": "error",
+	"n/no-path-concat": "error",
+	"n/prefer-global/buffer": ["error", "always"],
+	"n/prefer-global/console": ["error", "always"],
+	"n/prefer-global/process": ["error", "always"],
+	"n/prefer-global/url-search-params": ["error", "always"],
+	"n/prefer-global/url": ["error", "always"],
+	"n/prefer-promises/dns": "error",
+	"n/prefer-promises/fs": "error",
+	"n/prefer-node-protocol": "error"
+};
+/** eslint-plugin-n rules that Oxlint implements natively in its `node` plugin */
+const NATIVE_NODE_RULES = /* @__PURE__ */ new Set([
+	"no-exports-assign",
+	"no-new-require",
+	"no-path-concat"
+]);
+/**
+* eslint-plugin-n's `flat/recommended` rules plus the extra ones, run as an
+* Oxlint JS plugin. Rules Oxlint implements natively use the faster `node/*`
+* version instead. Derived from eslint-plugin-n's own preset so it follows new
+* releases.
+*/
+const nodeRules = Object.fromEntries(Object.entries({
+	...eslint_plugin_n.default.configs["flat/recommended"].rules,
+	...nodeBestPracticeRules
+}).map(([rule, value]) => {
+	const name = rule.replace(/^n\//, "");
+	return [NATIVE_NODE_RULES.has(name) ? `node/${name}` : rule, value];
+}));
+/**
+* Node.js Oxlint configuration that extends @jmlweb/oxlint-config-base.
+* Mirrors @jmlweb/eslint-config-node.
+*/
+const config = {
+	extends: [_jmlweb_oxlint_config_base.default],
+	plugins: [
+		"typescript",
+		"import",
+		"node"
+	],
+	jsPlugins: ["eslint-plugin-n"],
+	rules: nodeRules,
+	overrides: [{
+		files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
+		env: { node: true }
+	}]
+};
+//#endregion
+exports.default = config;

package/dist/index.d.cts

@@ -0,0 +1,9 @@
+import { OxlintConfig } from "oxlint";
+//#region src/index.d.ts
+/**
+ * Node.js Oxlint configuration that extends @jmlweb/oxlint-config-base.
+ * Mirrors @jmlweb/eslint-config-node.
+ */
+declare const config: OxlintConfig;
+//#endregion
+export { config as default };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { OxlintConfig } from "oxlint";
+//#region src/index.d.ts
+/**
+ * Node.js Oxlint configuration that extends @jmlweb/oxlint-config-base.
+ * Mirrors @jmlweb/eslint-config-node.
+ */
+declare const config: OxlintConfig;
+//#endregion
+export { config as default };

package/dist/index.js

@@ -0,0 +1,65 @@
+import baseConfig from "@jmlweb/oxlint-config-base";
+import eslintPluginN from "eslint-plugin-n";
+//#region src/index.ts
+/** Stricter or extra eslint-plugin-n rules, as in @jmlweb/eslint-config-node */
+const nodeBestPracticeRules = {
+	"n/no-process-exit": "error",
+	"n/no-missing-import": "error",
+	"n/no-missing-require": "error",
+	"n/no-unpublished-import": "error",
+	"n/no-unpublished-require": "error",
+	"n/no-extraneous-import": "error",
+	"n/no-extraneous-require": "error",
+	"n/no-deprecated-api": "warn",
+	"n/process-exit-as-throw": "error",
+	"n/no-callback-literal": "error",
+	"n/no-new-require": "error",
+	"n/no-path-concat": "error",
+	"n/prefer-global/buffer": ["error", "always"],
+	"n/prefer-global/console": ["error", "always"],
+	"n/prefer-global/process": ["error", "always"],
+	"n/prefer-global/url-search-params": ["error", "always"],
+	"n/prefer-global/url": ["error", "always"],
+	"n/prefer-promises/dns": "error",
+	"n/prefer-promises/fs": "error",
+	"n/prefer-node-protocol": "error"
+};
+/** eslint-plugin-n rules that Oxlint implements natively in its `node` plugin */
+const NATIVE_NODE_RULES = /* @__PURE__ */ new Set([
+	"no-exports-assign",
+	"no-new-require",
+	"no-path-concat"
+]);
+/**
+* eslint-plugin-n's `flat/recommended` rules plus the extra ones, run as an
+* Oxlint JS plugin. Rules Oxlint implements natively use the faster `node/*`
+* version instead. Derived from eslint-plugin-n's own preset so it follows new
+* releases.
+*/
+const nodeRules = Object.fromEntries(Object.entries({
+	...eslintPluginN.configs["flat/recommended"].rules,
+	...nodeBestPracticeRules
+}).map(([rule, value]) => {
+	const name = rule.replace(/^n\//, "");
+	return [NATIVE_NODE_RULES.has(name) ? `node/${name}` : rule, value];
+}));
+/**
+* Node.js Oxlint configuration that extends @jmlweb/oxlint-config-base.
+* Mirrors @jmlweb/eslint-config-node.
+*/
+const config = {
+	extends: [baseConfig],
+	plugins: [
+		"typescript",
+		"import",
+		"node"
+	],
+	jsPlugins: ["eslint-plugin-n"],
+	rules: nodeRules,
+	overrides: [{
+		files: ["**/*.{js,mjs,cjs,ts,mts,cts}"],
+		env: { node: true }
+	}]
+};
+//#endregion
+export { config as default };

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@jmlweb/oxlint-config-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Oxlint configuration for Node.js projects, extending @jmlweb/oxlint-config-base",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "linter",
+    "node",
+    "nodejs",
+    "oxc",
+    "oxlint",
+    "oxlint-config"
+  ],
+  "author": "jmlweb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jmlweb/tooling.git"
+  },
+  "bugs": "https://github.com/jmlweb/tooling/issues",
+  "homepage": "https://github.com/jmlweb/tooling/tree/main/packages/oxlint-config-node#readme",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "eslint-plugin-n": "^17.0.0 || ^18.0.0",
+    "oxlint": ">=1.87.0",
+    "oxlint-tsgolint": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "oxlint-tsgolint": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@jmlweb/oxlint-config-base": "0.1.0"
+  },
+  "devDependencies": {
+    "eslint-plugin-n": "^18.4.1",
+    "oxlint": "^1.87.0",
+    "oxlint-tsgolint": "^7.0.2003",
+    "tsdown": "~0.23.0",
+    "typescript": "^6.0.3",
+    "@jmlweb/tsconfig-internal": "0.0.1",
+    "@jmlweb/tsdown-config-base": "0.2.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist"
+  }
 }