@lewishowles/lint-config 0.1.3 → 0.3.0

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
 
@@ -8,7 +8,7 @@ Shared oxlint configuration for Lewis Howles projects. One package that every re
 bun add -d @lewishowles/lint-config @stylistic/eslint-plugin vite-plus
 ```
 
-`@stylistic/eslint-plugin` and `vite-plus` are peer dependencies — they must be installed in the consuming project so oxlint can resolve the JS plugins from `node_modules`.
+`@stylistic/eslint-plugin` and `vite-plus` are peer dependencies: they must be installed in the consuming project so oxlint can resolve the JS plugins from `node_modules`.
 
 ## Usage
 
@@ -19,28 +19,86 @@ 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 — 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"] }]
+	}
+}
+```
 
 ## 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 +111,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
 {
@@ -64,7 +122,7 @@ Ignore patterns are repo-specific, so they always live in your stub:
 
 ### Adding overrides
 
-Overrides are additive — shared overrides (if any) still apply, and your local ones are appended:
+Overrides are additive: shared overrides (if any) still apply, and your local ones are appended.
 
 ```json
 {
@@ -84,69 +142,32 @@ Overrides are additive — shared overrides (if any) still apply, and your local
 
 ### 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, `@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                                                                                                                                                 |
-
-## What stays repo-local
-
-- `ignorePatterns` — every repo has different build output and tool directories
-- `overrides` for repo-specific directories (e.g. `bin/**/*.js`, `src/cli/**/*.js`, `src/playwright/**/*.js`) — the file paths differ per repo, so they can't be generalised
-- Test-file rule relaxations (e.g. turning off `vite-plus/prefer-vite-plus-imports` in `*.d.ts`)
-- Additional plugins — only repos that need them
-
-## Merge semantics
-
-When a consumer stub extends a shared layer:
-
-- **Rules** shallow-merge by key — the consumer's 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).
+| 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  |
 
-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/**"]
-}
-```
+### Import sorting
 
-### Known limitation: `vite-plus`'s `lint` config field requires resolved objects, not string paths
+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.
 
-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.
+## What stays repo-local
 
-If your project uses `vite-plus`'s `lint` field rather than raw oxlint, resolve the chain yourself in `vite.config.js`:
+- `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
 
-```js
-import base from "@lewishowles/lint-config/base.json" with { type: "json" };
-import vue from "@lewishowles/lint-config/vue.json" with { type: "json" };
+## Merge semantics
 
-const lint = { ...vue, extends: [base, ...(vue.extends ?? [])] };
-```
+When a project's `.oxlintrc.json` extends a shared layer:
 
-`.oxlintrc.json` itself should stay untouched (string `extends`) for raw oxlint/editor consumption; this only applies to the `vite-plus` config path.
+- **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` 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,55 +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",
+	"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,30 @@
+import blockComments from "./rules/block-comments.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,
+		"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/configured-api-calls.js

@@ -0,0 +1,137 @@
+import { hasImmediateLineComment } from "../utils/source.js";
+
+// The built-in APIs that require a preceding comment by default.
+const builtInApis = new Set([
+	"onBeforeMount",
+	"onMounted",
+	"onBeforeUpdate",
+	"onUpdated",
+	"onBeforeUnmount",
+	"onUnmounted",
+	"onActivated",
+	"onDeactivated",
+	"onErrorCaptured",
+	"onRenderTracked",
+	"onRenderTriggered",
+	"onServerPrefetch",
+	"watch",
+	"watchEffect",
+	"watchPostEffect",
+	"watchSyncEffect",
+	"onClickOutside",
+]);
+
+/**
+ * Return whether a call is the documented initializer of a variable
+ * declaration.
+ *
+ * @param  {object}  sourceCode
+ *     The Oxlint source code object.
+ * @param  {object}  node
+ *     The call expression node.
+ *
+ * @returns  {boolean}
+ *     Whether the call is directly initialized by a documented declaration.
+ */
+function hasDocumentedVariableDeclaration(sourceCode, node) {
+	// The call's enclosing variable declarator, when there is one.
+	const declarator = node.parent;
+
+	if (declarator?.type !== "VariableDeclarator" || declarator.init !== node) {
+		return false;
+	}
+
+	// The declarator's enclosing variable declaration.
+	const declaration = declarator.parent;
+
+	return (
+		declaration?.type === "VariableDeclaration" && hasImmediateLineComment(sourceCode, declaration)
+	);
+}
+
+/**
+ * Return the configured API names for the rule.
+ *
+ * @param  {object}  context
+ *     The Oxlint rule context.
+ *
+ * @returns  {Set<string>}
+ *     The built-in and configured API names.
+ */
+function getConfiguredApis(context) {
+	// The rule's resolved options for the file currently being visited.
+	const options = context.options?.[0];
+	// The project-configured API names to add to the built-in list.
+	const additionalApis = options?.additionalApis ?? [];
+
+	return new Set([...builtInApis, ...additionalApis]);
+}
+
+/**
+ * Create the configured API call comment rule.
+ *
+ * @returns  {object}
+ *     The Oxlint rule definition.
+ */
+export default {
+	meta: {
+		docs: { description: "Require comments before configured API calls." },
+		type: "suggestion",
+		schema: [
+			{
+				type: "object",
+				properties: {
+					additionalApis: {
+						type: "array",
+						items: { type: "string" },
+						uniqueItems: true,
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{ additionalApis: [] }],
+	},
+
+	/**
+	 * 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 configured API call for a preceding comment.
+			 *
+			 * @param  {object}  node
+			 *     The call expression node.
+			 */
+			CallExpression(node) {
+				// Read fresh for every call: createOnce's visitor is shared across every file
+				// in the run, so caching this at closure-creation time would freeze the first
+				// file's options.
+				const configuredApis = getConfiguredApis(context);
+
+				if (node.callee.type !== "Identifier" || !configuredApis.has(node.callee.name)) {
+					return;
+				}
+
+				if (
+					hasDocumentedVariableDeclaration(context.sourceCode, node) ||
+					hasImmediateLineComment(context.sourceCode, node)
+				) {
+					return;
+				}
+
+				context.report({
+					message: "Configured API calls require an immediately preceding line comment.",
+					node,
+				});
+			},
+		};
+	},
+};