@lichens-innovation/eslint-plugin-coding-guide 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lichens Innovation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# eslint-plugin-coding-guide
+
+ESLint flat-config plugin enforcing Lichens Innovation TypeScript/React coding standards.
+
+[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+[![ESLint](https://img.shields.io/badge/ESLint-10-4B32C3.svg?style=flat-square&logo=eslint)](https://eslint.org/)
+[![Vitest](https://img.shields.io/badge/Vitest-4.1-6E9F18.svg?style=flat-square&logo=vitest)](https://vitest.dev/)
+[![Bun](https://img.shields.io/badge/Bun-1.4+-000000.svg?style=flat-square&logo=bun)](https://bun.sh/)
+
+- [eslint-plugin-coding-guide](#eslint-plugin-coding-guide)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Rules](#rules)
+  - [Development](#development)
+  - [All Scripts](#all-scripts)
+  - [Contributions](#contributions)
+  - [Library semantic versioning](#library-semantic-versioning)
+  - [License](#license)
+
+## Installation
+
+```bash
+npm install --save-dev @lichens-innovation/eslint-plugin-coding-guide
+```
+
+Peer dependency: `eslint >= 9.0.0` (flat config only).
+
+## Usage
+
+```js
+// eslint.config.js
+import codingGuide from "@lichens-innovation/eslint-plugin-coding-guide";
+
+export default [
+  codingGuide.configs.recommended,
+  // ...your other config objects
+];
+```
+
+Each rule can also be enabled individually via `codingGuide.rules["<rule-name>"]` under your own plugin key.
+
+## Rules
+
+All rules live under the `coding-guide/` namespace and are enabled by `configs.recommended`. See `docs/rules/<name>.md` for details on each.
+
+| Rule                                                                                             | Description                                                                                      |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| [`filename-convention-by-export-shape`](docs/rules/filename-convention-by-export-shape.md)       | Enforce filename conventions against a file's exported shape                                     |
+| [`hoist-static-component-constants`](docs/rules/hoist-static-component-constants.md)             | Disallow a static array/object literal declared inside a component body                          |
+| [`max-params-project`](docs/rules/max-params-project.md)                                         | Enforce a maximum number of parameters on project-owned functions                                |
+| [`no-explicit-undefined-optional`](docs/rules/no-explicit-undefined-optional.md)                 | Use `?` instead of an explicit `\| undefined` on params/properties that support it               |
+| [`no-exported-mutable-state`](docs/rules/no-exported-mutable-state.md)                           | Disallow exporting a mutable (let/var) module-scoped binding                                     |
+| [`no-hook-returning-jsx`](docs/rules/no-hook-returning-jsx.md)                                   | Disallow a use* hook returning JSX                                                               |
+| [`no-inline-array-chain-in-jsx`](docs/rules/no-inline-array-chain-in-jsx.md)                     | Disallow chained array methods directly inside a JSX expression                                  |
+| [`no-inline-curried-handler`](docs/rules/no-inline-curried-handler.md)                           | Disallow a curried handler factory declared as a local component variable                        |
+| [`no-inline-guard-chain-handler`](docs/rules/no-inline-guard-chain-handler.md)                   | Disallow a JSX prop arrow whose body is a long `&&` guard chain                                  |
+| [`no-inline-object-param-type`](docs/rules/no-inline-object-param-type.md)                       | Disallow inline object type literals on function parameters                                      |
+| [`no-inline-render-function`](docs/rules/no-inline-render-function.md)                           | Disallow calling a locally-declared render* helper function from within JSX                      |
+| [`no-jsx-in-variable`](docs/rules/no-jsx-in-variable.md)                                         | Disallow storing a JSX element/fragment in a variable                                            |
+| [`no-nested-try`](docs/rules/no-nested-try.md)                                                   | Disallow nesting a try statement inside another try block or catch handler                       |
+| [`no-non-hook-use-prefix`](docs/rules/no-non-hook-use-prefix.md)                                 | Disallow a use* named function whose body calls no hook                                          |
+| [`no-render-fn-in-usecallback`](docs/rules/no-render-fn-in-usecallback.md)                       | Disallow useCallback wrapping a JSX-returning or render*-named function                          |
+| [`no-tests-in-dunder-folder`](docs/rules/no-tests-in-dunder-folder.md)                           | Disallow test files inside a `__tests__` folder                                                  |
+| [`no-trivial-usememo`](docs/rules/no-trivial-usememo.md)                                         | Disallow useMemo whose body has no function call (likely unnecessary memoization)                |
+| [`no-unguarded-json-parse`](docs/rules/no-unguarded-json-parse.md)                               | Require `JSON.parse(...)` to be wrapped in a try/catch                                           |
+| [`prefer-element-ref-type`](docs/rules/prefer-element-ref-type.md)                               | Prefer `useRef<ElementRef<"tag">>(null)` over a raw `HTMLXxxElement` type argument               |
+| [`prefer-includes-over-or-chain`](docs/rules/prefer-includes-over-or-chain.md)                   | Prefer `Array#includes` over a chain of `===` comparisons against the same value                 |
+| [`prefer-jsx-short-circuit`](docs/rules/prefer-jsx-short-circuit.md)                             | Prefer `&&` short-circuit for optional JSX, with a boolean left side                             |
+| [`prefer-nullish-helpers`](docs/rules/prefer-nullish-helpers.md)                                 | Prefer `isNullish`/`!isNullish` over a manual null-and-undefined comparison pair                 |
+| [`prefer-positive-condition`](docs/rules/prefer-positive-condition.md)                           | Prefer a positive condition in a ternary over a negated one with swapped branches                |
+| [`prefer-props-with-children`](docs/rules/prefer-props-with-children.md)                         | Prefer `PropsWithChildren<Props>` over a hand-declared `children` property                       |
+| [`prefer-reactnode-over-jsxelement-union`](docs/rules/prefer-reactnode-over-jsxelement-union.md) | Prefer `ReactNode` over a `JSX.Element \| null \| undefined` union                               |
+| [`prefer-role-query-over-testid`](docs/rules/prefer-role-query-over-testid.md)                   | Prefer Testing Library's `*ByRole` queries over `*ByTestId`                                      |
+| [`prefer-some-over-find-check`](docs/rules/prefer-some-over-find-check.md)                       | Prefer `Array#some` over comparing `Array#find`'s result to undefined                            |
+| [`prefer-state-updater-form`](docs/rules/prefer-state-updater-form.md)                           | Prefer the updater-function form of a state setter when the new value depends on the current one |
+| [`require-effect-cleanup`](docs/rules/require-effect-cleanup.md)                                 | Require a cleanup return from a `useEffect` that registers a timer/listener/subscription         |
+| [`require-fallback-on-deep-chain`](docs/rules/require-fallback-on-deep-chain.md)                 | Require a `??` fallback on a deep optional chain                                                 |
+| [`require-numeric-enum-initializer`](docs/rules/require-numeric-enum-initializer.md)             | Require an explicit initializer on every enum member                                             |
+| [`require-usestate-useref-generic`](docs/rules/require-usestate-useref-generic.md)               | Require an explicit generic on `useState()`/`useRef()` when the initial value can't infer one    |
+| [`todo-ticket-ref`](docs/rules/todo-ticket-ref.md)                                               | Require a ticket reference in the TODO comment                                                   |
+
+## Development
+
+Install [Bun](https://bun.sh/docs/installation) 1.4+ (see `packageManager` in `package.json`), then:
+
+```bash
+bun install
+```
+
+## All Scripts
+
+| Command             | Description                                                       |
+| ------------------- | ----------------------------------------------------------------- |
+| `bun prepare`       | Installs husky git hooks (runs on `bun install`)                  |
+| `bun typecheck`     | Checks TypeScript types without emitting files                    |
+| `bun lint`          | Runs ESLint to check code quality                                 |
+| `bun lint:fix`      | Runs ESLint with `--fix`                                          |
+| `bun lint:package`  | Lints `package.json` via npm-package-json-lint                    |
+| `bun lint:unused`   | Finds unused files, exports, and dependencies (via knip)          |
+| `bun format`        | Formats all files using Prettier according to .prettierrc rules   |
+| `bun format:check`  | Checks if files are formatted according to Prettier rules         |
+| `bun build`         | Cleans `dist`, then Vite library build (`src/index.ts` → `dist/`) |
+| `bun test`          | Runs tests using Vitest                                           |
+| `bun test:coverage` | Runs tests with a Vitest coverage report                          |
+
+## Contributions
+
+Contributions to the project are made by improving the current codebase and then creating a Pull Request. Every PR runs the CI workflow (lint, typecheck, test, build). When the PR is merged into `main`, the release CI pipeline runs automatically. [semantic-release](https://semantic-release.gitbook.io/) determines the next version from conventional commit messages, updates `CHANGELOG.md` and `package.json`, and publishes the new version — no manual version bump required.
+
+## Library semantic versioning
+
+Versioning is automated by [semantic-release](https://semantic-release.gitbook.io/) using [Conventional Commits](https://www.conventionalcommits.org/). The release type is derived from commit message prefixes:
+
+| Commit prefix                 | Release type                                    |
+| ----------------------------- | ----------------------------------------------- |
+| `fix:`                        | `PATCH` — backward-compatible bug fix           |
+| `feat:`                       | `MINOR` — new backward-compatible functionality |
+| `feat!:` / `BREAKING CHANGE:` | `MAJOR` — incompatible API change               |
+
+Follow [Semantic Versioning](https://semver.org/#summary) (`MAJOR.MINOR.PATCH`) when writing commit messages — the tooling takes care of the rest. Commitlint requires a **scope** (e.g. `feat(rules): add no-foo-bar`).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/ast-utils.d.ts

@@ -0,0 +1,2 @@
+import { TSESTree } from '@typescript-eslint/utils';
+export declare const getChildNodes: (node: TSESTree.Node) => TSESTree.Node[];

package/dist/configs/recommended.d.ts

@@ -0,0 +1,6 @@
+import { Linter } from 'eslint';
+interface CodingGuidePlugin {
+    rules: Record<string, unknown>;
+}
+export declare const recommended: (plugin: CodingGuidePlugin) => Linter.Config;
+export {};

package/dist/create-rule.d.ts

@@ -0,0 +1,4 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+export declare const createRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};

package/dist/eslint.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("typescript-eslint").FlatConfig.ConfigArray;
+export default _default;

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { Linter } from 'eslint';
+export type { Options as MaxParamsProjectOptions } from './rules/max-params-project.js';
+export type { Options as RequireFallbackOnDeepChainOptions } from './rules/require-fallback-on-deep-chain.js';
+export type { Options as TodoTicketRefOptions } from './rules/todo-ticket-ref.js';
+declare const plugin: {
+    readonly meta: {
+        readonly name: "@lichens-innovation/eslint-plugin-coding-guide";
+    };
+    readonly rules: {
+        "filename-convention-by-export-shape": import('@typescript-eslint/utils/ts-eslint').RuleModule<"genericBasename" | "hookFilename" | "suffixFilename", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "hoist-static-component-constants": import('@typescript-eslint/utils/ts-eslint').RuleModule<"hoist", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "max-params-project": import('@typescript-eslint/utils/ts-eslint').RuleModule<"exceed", [number | import('./index.js').MaxParamsProjectOptions], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-explicit-undefined-optional": import('@typescript-eslint/utils/ts-eslint').RuleModule<"useOptionalModifier" | "redundantUndefined", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-exported-mutable-state": import('@typescript-eslint/utils/ts-eslint').RuleModule<"noMutableExport", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-hook-returning-jsx": import('@typescript-eslint/utils/ts-eslint').RuleModule<"hookReturnsJsx", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-inline-array-chain-in-jsx": import('@typescript-eslint/utils/ts-eslint').RuleModule<"precompute", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-inline-curried-handler": import('@typescript-eslint/utils/ts-eslint').RuleModule<"extractToUtils", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-inline-guard-chain-handler": import('@typescript-eslint/utils/ts-eslint').RuleModule<"extractHandler", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-inline-object-param-type": import('@typescript-eslint/utils/ts-eslint').RuleModule<"extractInterface", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-inline-render-function": import('@typescript-eslint/utils/ts-eslint').RuleModule<"extractSubcomponent", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-jsx-in-variable": import('@typescript-eslint/utils/ts-eslint').RuleModule<"declareComponent", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-nested-try": import('@typescript-eslint/utils/ts-eslint').RuleModule<"nestedTry", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-non-hook-use-prefix": import('@typescript-eslint/utils/ts-eslint').RuleModule<"misnamed", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-render-fn-in-usecallback": import('@typescript-eslint/utils/ts-eslint').RuleModule<"extractSubcomponent", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-tests-in-dunder-folder": import('@typescript-eslint/utils/ts-eslint').RuleModule<"colocate", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-trivial-usememo": import('@typescript-eslint/utils/ts-eslint').RuleModule<"unnecessaryMemo", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "no-unguarded-json-parse": import('@typescript-eslint/utils/ts-eslint').RuleModule<"unguarded", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-element-ref-type": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferElementRef", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-includes-over-or-chain": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferIncludes", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-jsx-short-circuit": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferShortCircuit" | "requireBooleanGuard", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-nullish-helpers": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferNotNullish" | "preferNullish", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-positive-condition": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferPositive", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-props-with-children": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferPropsWithChildren", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-reactnode-over-jsxelement-union": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferReactNode", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-role-query-over-testid": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferRole", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-some-over-find-check": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferSome", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "prefer-state-updater-form": import('@typescript-eslint/utils/ts-eslint').RuleModule<"preferUpdaterForm", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "require-effect-cleanup": import('@typescript-eslint/utils/ts-eslint').RuleModule<"requireCleanup", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "require-fallback-on-deep-chain": import('@typescript-eslint/utils/ts-eslint').RuleModule<"requireFallback", [import('./index.js').RequireFallbackOnDeepChainOptions], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "require-numeric-enum-initializer": import('@typescript-eslint/utils/ts-eslint').RuleModule<"missingInitializer", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "require-usestate-useref-generic": import('@typescript-eslint/utils/ts-eslint').RuleModule<"requireGeneric", [], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+        "todo-ticket-ref": import('@typescript-eslint/utils/ts-eslint').RuleModule<"missingTicket" | "missingTicketWithCommentPattern" | "missingTicketWithDescription", [import('./index.js').TodoTicketRefOptions], unknown, import('@typescript-eslint/utils/ts-eslint').RuleListener> & {
+            name: string;
+        };
+    };
+};
+export declare const configs: {
+    recommended: Linter.Config;
+};
+export default plugin;