@lewishowles/lint-config 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.4.0: 2026-08-28
+
+### New rules
+
+- Added `comments/class-documentation`: requires a block comment on class declarations and const-assigned class expressions, JSDoc on constructors and ordinary methods, return-aware JSDoc on getters and setters, and line comments on instance and static fields. Ships in the opt-in `comments.json` layer.
+
+### Fixes
+
+- A directive comment (`eslint-`, `oxlint-`, and similar) sitting between a doc comment and its code is now reported, instead of the doc being treated as attached to the code.
+- Documentation placed before an exported declaration is now recognised.
+- `using` and `await using` declarations now require a preceding line comment, like `const` and `let`.
+
+Earlier versions predate this changelog; see the git history for their changes.

package/README.md

@@ -1,6 +1,6 @@
 # @lewishowles/lint-config
 
-Shared oxlint configuration for Lewis Howles projects. One package that every repo extends, so lint setup stops being duplicated and drifting across the ecosystem.
+Shared Oxlint configuration for Lewis Howles projects. Projects extend this package to keep their lint configuration consistent across projects, instead of copying and maintaining the same rules everywhere.
 
 ## Installation
 
@@ -19,28 +19,94 @@ Create a `.oxlintrc.json` in your project root that extends the appropriate laye
 ```json
 {
 	"extends": ["./node_modules/@lewishowles/lint-config/base.json"],
+	"env": { "builtin": true, "browser": true },
 	"ignorePatterns": ["**/dist/*", ".codebase-memory/**"]
 }
 ```
 
+Note that `env` has to be redeclared here: Oxlint doesn't yet merge it through `extends`, so `base.json`'s own `env` never reaches your project. See [known limitations](docs/limitations.md) for why.
+
 ### Vue layer (Vue 3 projects)
 
 ```json
 {
 	"extends": ["./node_modules/@lewishowles/lint-config/vue.json"],
+	"env": { "builtin": true, "browser": true },
+	"globals": {
+		"defineEmits": "readonly",
+		"defineExpose": "readonly",
+		"defineModel": "readonly",
+		"defineOptions": "readonly",
+		"defineProps": "readonly",
+		"defineSlots": "readonly",
+		"withDefaults": "readonly"
+	},
+	"ignorePatterns": ["**/dist/*", ".codebase-memory/**"]
+}
+```
+
+The Vue layer extends `base.json` internally, so you only need to extend `vue.json`. The same `env`/`globals` limitation applies here too, which is why both are redeclared above.
+
+### Comment formatting (optional)
+
+Add the comments layer alongside the base or Vue layer to enforce the comment-formatting rules, variable-declaration documentation, JSDoc on named functions and first-level object methods, documentation directly after each Vue `<script setup>` opening tag, and block comments for runtime `defineProps` properties:
+
+```json
+{
+	"extends": [
+		"./node_modules/@lewishowles/lint-config/base.json",
+		"./node_modules/@lewishowles/lint-config/comments.json"
+	],
+	"env": { "builtin": true, "browser": true },
 	"ignorePatterns": ["**/dist/*", ".codebase-memory/**"]
 }
 ```
 
-The Vue layer extends `base.json` internally, so you only need to extend `vue.json`.
+The Vue component rule reads the raw `.vue` file because Oxlint's JS Plugin API only receives the extracted script block. The comments layer loads its plugin for you, so there's no relative `jsPlugins` path to add. To pick rules yourself instead, add the plugin directly:
+
+```json
+{
+	"jsPlugins": [
+		{
+			"name": "comments",
+			"specifier": "@lewishowles/lint-config/comments/plugin"
+		}
+	],
+	"rules": {
+		"comments/line-comments": "error"
+	}
+}
+```
+
+The `comments/vue-prop-documentation` rule requires an indented block comment immediately before every runtime property in `defineProps`. A matching comment on a `defineProps` property also documents its `withDefaults` entry; type-only props are not checked.
+
+The `comments/vue-emit-documentation` rule requires an indented block comment immediately before every runtime property in `defineEmits`. Function-valued events also require the normal JSDoc tags; array-form and type-only emits are not checked.
+
+The `comments/configured-api-calls` rule requires an immediately preceding line comment before configured bare-identifier calls such as Vue lifecycle hooks, reactive effects, and `onClickOutside`. A documented variable declaration covers a direct call initializer; member-expression calls are out of scope. Add project-specific APIs without replacing the built-in list:
+
+```json
+{
+	"rules": {
+		"comments/configured-api-calls": ["error", { "additionalApis": ["subscribe"] }]
+	}
+}
+```
+
+The `comments/class-documentation` rule requires an immediately preceding block comment before class declarations and const-assigned class expressions. Constructors, methods, getters, and setters require full JSDoc; constructors never need an `@returns` tag, and getters and setters need one only when they return a value. Instance and static fields require an immediately preceding line comment.
+
+### `vp check` configuration
+
+The `vp check` and `vp lint` commands read Oxlint settings only from a `lint` block in `vite.config.js`; they do not read `.oxlintrc.json` directly. If `vite.config.js` is missing, they silently use an unrelated default configuration. You may still see plausible warnings and exit codes, but none of your rules are applied.
+
+Each consuming repo needs a `vite.config.js` with a `lint` block built from the config layer(s) and the repo's `.oxlintrc.json`, imported as JSON. Verify the setup with `vp lint --print-config <file>` and check that your real values, not defaults, are active.
 
 ## Customising
 
-Your `.oxlintrc.json` stub can override rules, add ignore patterns, add overrides, or add plugins on top of the shared layer.
+Your project's `.oxlintrc.json` can override rules, add ignore patterns, add overrides, or add plugins on top of the shared layer.
 
 ### Overriding a rule
 
-To change the severity or options of a rule defined in the shared layer, redeclare it in your stub: your value wins.
+To change the severity or options of a rule defined in the shared layer, redeclare it in your project config: your value wins.
 
 ```json
 {
@@ -53,7 +119,7 @@ To change the severity or options of a rule defined in the shared layer, redecla
 
 ### Adding ignore patterns
 
-Ignore patterns are repo-specific, so they always live in your stub:
+Ignore patterns are project-specific, so they always live in your project config:
 
 ```json
 {
@@ -84,75 +150,32 @@ Overrides are additive: shared overrides (if any) still apply, and your local on
 
 ### Adding plugins
 
-Plugins are additive and deduplicated: your local plugins are added to the shared ones. Note that oxlint only supports its built-in plugin names (`oxc`, `typescript`, `unicorn`, `vue`, etc.); there is no `playwright` or `vitest` plugin. Test-file-specific behaviour is handled via `overrides`, not plugins.
+Plugins are additive and deduplicated: your local plugins are added to the shared ones. Oxlint's `plugins` field only accepts built-in plugin names, such as `oxc`, `typescript`, `unicorn`, and `vue`; there's no `playwright` or `vitest` plugin. Custom JS plugins, like this package's `comments` plugin, load through `jsPlugins` instead. Test-file-specific behaviour is handled via `overrides`, not plugins.
 
 ## Layers
 
-| Layer  | File        | Contents                                                                                                                                                                                                                              |
-| ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `base` | `base.json` | Correctness rules, named-import member sorting, `@stylistic` formatting rules, `vite-plus/prefer-vite-plus-imports`, `oxc` + `typescript` + `unicorn` plugins, browser env, node env for config files (`vite.config.*`, `vitest.config.*`, `playwright*.config.*`) |
-| `vue`  | `vue.json`  | Extends `base`. Adds `vue` plugin, Vue compiler macros as globals, Vue-specific rules                                                                                                                                                 |
-
-### Import sorting ownership
+| Layer      | File            | Contents                                                                               |
+| ---------- | --------------- | -------------------------------------------------------------------------------------- |
+| `base`     | `base.json`     | Correctness and formatting rules, import sorting, `oxc`/`typescript`/`unicorn` plugins |
+| `comments` | `comments.json` | Optional comment-formatting rules, variable-declaration documentation, JSDoc checks    |
+| `vue`      | `vue.json`      | Extends `base`, adds the `vue` plugin, Vue compiler macro globals, Vue-specific rules  |
 
-The base layer sorts named members within each import declaration. It sets `ignoreDeclarationSort: true` because Oxlint reports declaration-row ordering but does not auto-fix it.
+### Import sorting
 
-Consumers that want import declaration rows sorted should enable Oxfmt's `sortImports` option in their local `.oxfmtrc.json`. This keeps member sorting in the shared Oxlint layer and declaration ordering in the formatter that can fix it.
+The base layer sorts named members within each import statement, but leaves declaration order (which import comes first) to Oxfmt: enable Oxfmt's `sortImports` option in your local `.oxfmtrc.json` if you want that sorted and fixed automatically.
 
 ## What stays repo-local
 
-- `ignorePatterns`, since every repo has different build output and tool directories
-- `overrides` for repo-specific directories (e.g. `bin/**/*.js`, `src/cli/**/*.js`, `src/playwright/**/*.js`), since the file paths differ per repo and can't be generalised
-- Test-file rule relaxations (e.g. turning off `vite-plus/prefer-vite-plus-imports` in `*.d.ts`)
-- Additional plugins, only for repos that need them
+- `ignorePatterns`, since every project has different build output and tool directories
+- `overrides` for project-specific directories (e.g. `bin/**/*.js`, `src/cli/**/*.js`, `src/playwright/**/*.js`), since the file paths differ per project and can't be generalised
+- Rule relaxations for specific file patterns (e.g. turning off `vite-plus/prefer-vite-plus-imports` in generated `.d.ts` files)
+- Additional plugins, only for projects that need them
 
 ## Merge semantics
 
-When a consumer stub extends a shared layer:
+When a project's `.oxlintrc.json` extends a shared layer:
 
-- **Rules** shallow-merge by key: the consumer's value wins for any rule defined in both
+- **Rules** shallow-merge by key: your value wins for any rule defined in both
 - **Overrides** are additive: both shared and local `overrides` entries apply, including any `env` declared inside an override block
-- **Plugins** are additive: both shared and local `plugins`/`jsPlugins` are loaded (deduplicated)
-
-### Known oxlint limitation: top-level `env`, `globals`, and `ignorePatterns` don't merge through `extends`
-
-oxlint currently drops top-level `env`, `globals`, and `ignorePatterns` from an extended config file entirely: they only take effect if declared directly in the file oxlint is invoked with. This is an open upstream bug: [oxc-project/oxc#20087](https://github.com/oxc-project/oxc/issues/20087) (open as of oxlint 1.72.0).
-
-In practice this means:
-
-- `base.json`'s `env` (`builtin`, `browser`) and `vue.json`'s Vue macro `globals` (`defineProps`, `defineEmits`, etc.) will **not** reach a consumer that only does `{ "extends": ["./node_modules/@lewishowles/lint-config/vue.json"] }`: every global from the shared layer will be flagged by `no-undef`.
-- Any `ignorePatterns` this package might declare would be silently dropped the same way, so it deliberately ships none. See "What stays repo-local" below.
-
-Until this is fixed upstream, redeclare the `env`/`globals` you need directly in your project's `.oxlintrc.json`, even though `base.json`/`vue.json` already declare them:
-
-```json
-{
-	"extends": ["./node_modules/@lewishowles/lint-config/vue.json"],
-	"env": { "builtin": true, "browser": true },
-	"globals": {
-		"defineEmits": "readonly",
-		"defineExpose": "readonly",
-		"defineModel": "readonly",
-		"defineOptions": "readonly",
-		"defineProps": "readonly",
-		"defineSlots": "readonly",
-		"withDefaults": "readonly"
-	},
-	"ignorePatterns": ["**/dist/*", ".codebase-memory/**"]
-}
-```
-
-### Known limitation: `vite-plus`'s `lint` config field requires resolved objects, not string paths
-
-Raw oxlint (CLI, editor integrations) accepts `"extends": ["./node_modules/@lewishowles/lint-config/vue.json"]` as string paths and resolves them at load time. `vite-plus`, when a project routes its oxlint config through `vite.config.js`'s `lint` field (importing `.oxlintrc.json` as JSON and handing it to `vp check`/`vp lint`), does not resolve string paths in `extends`: every entry, at every nesting level, must already be a plain object. This means `vue.json`'s own internal `extends: ["./base.json"]` also breaks one level deeper.
-
-If your project uses `vite-plus`'s `lint` field rather than raw oxlint, resolve the chain yourself in `vite.config.js`:
-
-```js
-import base from "@lewishowles/lint-config/base.json" with { type: "json" };
-import vue from "@lewishowles/lint-config/vue.json" with { type: "json" };
-
-const lint = { ...vue, extends: [base, ...(vue.extends ?? [])] };
-```
-
-`.oxlintrc.json` itself should stay untouched (string `extends`) for raw oxlint/editor consumption; this only applies to the `vite-plus` config path.
+- **Plugins** are additive: both shared and local `plugins`/`jsPlugins` load, deduplicated
+- **`env`, `globals`, and `ignorePatterns` don't merge through `extends` at all** (an open Oxlint bug), which is why the usage examples above redeclare `env`/`globals` directly. See [known limitations](docs/limitations.md) for the full detail, including the separate `vite-plus` caveat around resolving `extends` paths.

package/base.json

@@ -1,61 +1,61 @@
 {
-  "plugins": ["oxc", "typescript", "unicorn"],
-  "jsPlugins": [
-    "@stylistic/eslint-plugin",
-    {
-      "name": "vite-plus",
-      "specifier": "vite-plus/oxlint-plugin"
-    }
-  ],
-  "categories": {
-    "correctness": "error"
-  },
-  "env": {
-    "builtin": true,
-    "browser": true
-  },
-  "rules": {
-    "no-case-declarations": "error",
-    "no-empty": "error",
-    "no-fallthrough": "error",
-    "no-prototype-builtins": "error",
-    "no-redeclare": "error",
-    "no-regex-spaces": "error",
-    "no-undef": "error",
-    "no-unexpected-multiline": "error",
-    "no-useless-assignment": "error",
-    "preserve-caught-error": "error",
-    "sort-imports": [
-      "error",
-      {
-        "ignoreDeclarationSort": true
-      }
-    ],
+	"plugins": ["oxc", "typescript", "unicorn"],
+	"jsPlugins": [
+		"@stylistic/eslint-plugin",
+		{
+			"name": "vite-plus",
+			"specifier": "vite-plus/oxlint-plugin"
+		}
+	],
+	"categories": {
+		"correctness": "error"
+	},
+	"env": {
+		"builtin": true,
+		"browser": true
+	},
+	"rules": {
+		"no-case-declarations": "error",
+		"no-empty": "error",
+		"no-fallthrough": "error",
+		"no-prototype-builtins": "error",
+		"no-redeclare": "error",
+		"no-regex-spaces": "error",
+		"no-undef": "error",
+		"no-unexpected-multiline": "error",
+		"no-useless-assignment": "error",
+		"preserve-caught-error": "error",
+		"sort-imports": [
+			"error",
+			{
+				"ignoreDeclarationSort": true
+			}
+		],
 
-    "@stylistic/no-confusing-arrow": "error",
-    "@stylistic/padding-line-between-statements": [
-      "error",
-      { "blankLine": "always", "prev": "const", "next": "let" },
-      { "blankLine": "always", "prev": "let", "next": "const" },
-      { "blankLine": "always", "prev": "*", "next": "break" },
-      { "blankLine": "always", "prev": ["const", "let"], "next": "*" },
-      { "blankLine": "always", "prev": "*", "next": "return" },
-      { "blankLine": "any", "prev": "const", "next": "const" },
-      { "blankLine": "any", "prev": "let", "next": "let" },
-      { "blankLine": "always", "prev": "multiline-const", "next": "*" },
-      { "blankLine": "always", "prev": "*", "next": "multiline-const" }
-    ],
+		"@stylistic/no-confusing-arrow": "error",
+		"@stylistic/padding-line-between-statements": [
+			"error",
+			{ "blankLine": "always", "prev": "const", "next": "let" },
+			{ "blankLine": "always", "prev": "let", "next": "const" },
+			{ "blankLine": "always", "prev": "*", "next": "break" },
+			{ "blankLine": "always", "prev": ["const", "let"], "next": "*" },
+			{ "blankLine": "always", "prev": "*", "next": "return" },
+			{ "blankLine": "any", "prev": "const", "next": "const" },
+			{ "blankLine": "any", "prev": "let", "next": "let" },
+			{ "blankLine": "always", "prev": "multiline-const", "next": "*" },
+			{ "blankLine": "always", "prev": "*", "next": "multiline-const" }
+		],
 
-    "vite-plus/prefer-vite-plus-imports": "error"
-  },
-  "overrides": [
-    {
-      "files": ["**/vite.config.*", "**/vitest.config.*", "**/playwright*.config.*"],
-      "env": { "node": true }
-    }
-  ],
-  "options": {
-    "typeAware": false,
-    "typeCheck": false
-  }
+		"vite-plus/prefer-vite-plus-imports": "error"
+	},
+	"overrides": [
+		{
+			"files": ["**/vite.config.*", "**/vitest.config.*", "**/playwright*.config.*"],
+			"env": { "node": true }
+		}
+	],
+	"options": {
+		"typeAware": false,
+		"typeCheck": false
+	}
 }

package/comments/plugin.js

@@ -0,0 +1,32 @@
+import blockComments from "./rules/block-comments.js";
+import classDocumentation from "./rules/class-documentation.js";
+import configuredApiCalls from "./rules/configured-api-calls.js";
+import functionDocumentation from "./rules/function-documentation.js";
+import jsdocTagFormatting from "./rules/jsdoc-tag-formatting.js";
+import lineComments from "./rules/line-comments.js";
+import maxLineLength from "./rules/max-line-length.js";
+import placement from "./rules/placement.js";
+import sentencePunctuation from "./rules/sentence-punctuation.js";
+import variableDeclarations from "./rules/variable-declarations.js";
+import vueComponentDocumentation from "./rules/vue-component-documentation.js";
+import vueEmitDocumentation from "./rules/vue-emit-documentation.js";
+import vuePropDocumentation from "./rules/vue-prop-documentation.js";
+
+export default {
+	meta: { name: "comments" },
+	rules: {
+		"block-comments": blockComments,
+		"class-documentation": classDocumentation,
+		"configured-api-calls": configuredApiCalls,
+		"function-documentation": functionDocumentation,
+		"jsdoc-tag-formatting": jsdocTagFormatting,
+		"line-comments": lineComments,
+		"max-line-length": maxLineLength,
+		placement,
+		"sentence-punctuation": sentencePunctuation,
+		"variable-declarations": variableDeclarations,
+		"vue-component-documentation": vueComponentDocumentation,
+		"vue-emit-documentation": vueEmitDocumentation,
+		"vue-prop-documentation": vuePropDocumentation,
+	},
+};

package/comments/rules/block-comments.js

@@ -0,0 +1,70 @@
+import { formatJSDocBlockStructure, isJSDoc } from "../utils/jsdoc.js";
+import { getCommentText, replaceMinimalComment } from "../utils/source.js";
+
+/**
+ * Create the JSDoc block-comment formatting rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Format JSDoc block comments." },
+		fixable: "code",
+		type: "layout",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor functions for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Format every JSDoc comment's block structure in the file.
+			 */
+			Program() {
+				for (const comment of context.sourceCode.getAllComments()) {
+					if (comment.type !== "Block") {
+						continue;
+					}
+
+					// The comment's raw source text.
+					const commentText = getCommentText(context.sourceCode, comment);
+
+					if (!isJSDoc(commentText)) {
+						continue;
+					}
+
+					// The comment, with its block structure and delimiters normalised.
+					const formattedComment = formatJSDocBlockStructure(context.sourceCode, comment);
+
+					if (formattedComment === commentText) {
+						continue;
+					}
+
+					context.report({
+						/**
+						 * Apply the formatted replacement to the comment.
+						 *
+						 * @param  {object}  fixer
+						 *     The Oxlint fixer.
+						 *
+						 * @returns  {object}
+						 *     The fix to apply.
+						 */
+						fix: (fixer) => {
+							return replaceMinimalComment(fixer, comment, commentText, formattedComment);
+						},
+						message: "JSDoc comments must use the configured block format.",
+						node: comment,
+					});
+				}
+			},
+		};
+	},
+};

package/comments/rules/class-documentation.js

@@ -0,0 +1,131 @@
+import { getDocumentationNode, reportFunctionDocumentation } from "../utils/documentation.js";
+import { hasImmediateBlockComment, hasImmediateLineComment } from "../utils/source.js";
+
+/**
+ * Create the class-documentation rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: {
+			description:
+				"Require documentation for classes, their methods, getters, setters, and fields.",
+		},
+		type: "suggestion",
+	},
+	/**
+	 * Create the rule's node visitors.
+	 *
+	 * @param  {object}  context
+	 *     The Oxlint rule context.
+	 *
+	 * @returns  {object}
+	 *     The visitor functions for this rule.
+	 */
+	createOnce(context) {
+		return {
+			/**
+			 * Check a class declaration for a preceding block comment.
+			 *
+			 * @param  {object}  node
+			 *     The class declaration node.
+			 */
+			ClassDeclaration(node) {
+				// Resolves any export wrapper before checking for documentation.
+				const documentationNode = getDocumentationNode(node);
+
+				if (!hasImmediateBlockComment(context.sourceCode, documentationNode)) {
+					context.report({
+						message: "Classes require an immediately preceding block comment.",
+						node: documentationNode,
+					});
+				}
+			},
+			/**
+			 * Check class methods for required JSDoc blocks and tags. Constructors are
+			 * exempt from the @returns requirement.
+			 *
+			 * @param  {object}  node
+			 *     The method-definition node.
+			 */
+			MethodDefinition(node) {
+				if (node.kind === "constructor") {
+					reportFunctionDocumentation(context, node, node.value, {
+						requiresReturns: false,
+						subject: "Constructors",
+					});
+
+					return;
+				}
+
+				if (node.kind === "get") {
+					reportFunctionDocumentation(context, node, node.value, {
+						subject: "Getters",
+					});
+
+					return;
+				}
+
+				if (node.kind === "set") {
+					reportFunctionDocumentation(context, node, node.value, {
+						subject: "Setters",
+					});
+
+					return;
+				}
+
+				if (node.kind === "method") {
+					reportFunctionDocumentation(context, node, node.value, {
+						subject: "Methods",
+					});
+				}
+			},
+			/**
+			 * Check instance and static fields for a preceding line comment.
+			 *
+			 * @param  {object}  node
+			 *     The property-definition node.
+			 */
+			PropertyDefinition(node) {
+				if (hasImmediateLineComment(context.sourceCode, node)) {
+					return;
+				}
+
+				// Static and instance fields share the requirement; only the wording differs.
+				const message = node.static
+					? "Static fields require an immediately preceding line comment."
+					: "Instance fields require an immediately preceding line comment.";
+
+				context.report({ message, node });
+			},
+			/**
+			 * Check a const class expression for a preceding block comment.
+			 *
+			 * @param  {object}  node
+			 *     The variable declarator node.
+			 */
+			VariableDeclarator(node) {
+				if (
+					node.parent?.kind !== "const" ||
+					node.parent.declarations.length !== 1 ||
+					node.id?.type !== "Identifier" ||
+					node.init?.type !== "ClassExpression"
+				) {
+					return;
+				}
+
+				// Resolves any export wrapper before checking for documentation.
+				const documentationNode = getDocumentationNode(node.parent);
+
+				if (!hasImmediateBlockComment(context.sourceCode, documentationNode)) {
+					context.report({
+						message: "Classes require an immediately preceding block comment.",
+						node: documentationNode,
+					});
+				}
+			},
+		};
+	},
+};