@sinemacula/coding-standards 1.8.3 → 1.9.0

package/README.md

@@ -110,6 +110,52 @@ After installing the npm package, extend the shared Biome config from your proje
 math against `node_modules/` required). Project-specific `files.includes` and `files.excludes` stay in the consumer
 config.
 
+### ESLint (JavaScript / TypeScript)
+
+ESLint runs *alongside* Biome, not in place of it. Biome keeps owning formatting and the fast syntactic lint; ESLint
+adds only the two things Biome structurally cannot express: this package's custom structural rules and the opt-in
+type-aware rules (the curated typescript-eslint set plus the type-driven custom rules). Add the linter, the
+typescript-eslint tooling, and this package to your dev dependencies:
+
+```bash
+npm install --save-dev eslint typescript typescript-eslint eslint-plugin-jsdoc @sinemacula/coding-standards
+```
+
+The package exposes two flat-config entry points:
+
+- `@sinemacula/coding-standards/js/eslint` - the base layer of syntax-only custom rules; needs no `tsconfig`, so it
+  stays cheap and runs anywhere Biome runs.
+- `@sinemacula/coding-standards/js/eslint/type-checked` - the opt-in type-aware layer. It includes the base layer and
+  adds the cross-file / type-driven rules, so it needs a consumer `tsconfig`; use it in place of the base layer where
+  one exists.
+
+Create an `eslint.config.js` (or `.qlty/configs/eslint.config.js` when wired through Qlty) that spreads the layer you
+want. Without a `tsconfig`, use the base layer:
+
+```js
+import sm from '@sinemacula/coding-standards/js/eslint';
+
+export default [...sm];
+```
+
+Where a `tsconfig` exists, use the type-aware layer instead (it already carries the base rules):
+
+```js
+import typeChecked from '@sinemacula/coding-standards/js/eslint/type-checked';
+
+export default [...typeChecked];
+```
+
+When wiring ESLint through Qlty, the shared eslint plugin sandbox installs only `eslint`, `jest`, and `prettier` by
+default, so the flat config's imports of this package and `typescript-eslint` fail to resolve. Widen the install
+filter in your `.qlty/qlty.toml` so the sandbox carries them (this repository's `source.toml` exports the same
+override, but source-exported plugin definitions do not reliably propagate, so mirror it consumer-side):
+
+```toml
+[plugins.definitions.eslint]
+package_filters = ["@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc"]
+```
+
 ### Knip (JavaScript / TypeScript)
 
 ```json
@@ -141,6 +187,7 @@ tag = "<version>"
 | `php/phpstan-base.neon`       | PHPStan      | Base config (org-wide ignored errors + settings)       |
 | `js/biome.json`               | Biome        | JavaScript / TypeScript formatter + linter rules       |
 | `js/knip.json`                | Knip         | Unused-export detection rules                          |
+| `js/eslint/`                  | ESLint       | Custom structural + type-aware rules; runs with Biome  |
 | `markdown/.markdownlint.json` | markdownlint | Markdown linting rules                                 |
 | `yaml/.yamllint.yaml`         | yamllint     | YAML linting rules                                     |
 | `shell/.shellcheckrc`         | ShellCheck   | Shell script linting rules                             |
@@ -150,7 +197,8 @@ tag = "<version>"
 ## Rules
 
 These are the custom rules this package enforces on top of PSR-12. A deliberate exception can be bypassed with the
-native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <identifier>` for a rule.
+native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <identifier>` for a rule,
+`// eslint-disable-next-line <rule>` for an ESLint rule.
 
 ### PHPCS sniffs
 
@@ -186,6 +234,32 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 |------------|----------|
 | `sineMacula.mutableStaticProperty` | Static properties written at runtime; `@managed-static` opts out. |
 
+### ESLint rules
+
+All rules run in the base layer except `boolean-method-name`, which resolves return types and so requires the opt-in
+type-checked layer.
+
+| Rule | Enforces |
+|------|----------|
+| `@sinemacula/no-interface-prefix` | Interface and type-alias names must not use the Hungarian `I` prefix. |
+| `@sinemacula/require-readonly-public-property` | Public class properties (declared or promoted) must be `readonly`. |
+| `@sinemacula/valid-enum-member-name` | Enum members must be declared in `SCREAMING_SNAKE_CASE`. |
+| `@sinemacula/boolean-method-name` | Boolean-returning methods need an is/has/can prefix; `@imperative` exempt. |
+| `@sinemacula/no-mutable-static` | No mutable exported bindings or mutable `static` class fields; test code exempt. |
+| `@sinemacula/max-methods-per-class` | A single class may declare at most 20 methods; test code exempt. |
+| `@sinemacula/no-base-error` | Throw a domain-specific `Error` subclass, never the base `Error`. |
+| `@sinemacula/require-copyright` | Every file must carry a documentation comment with `@copyright` and `@author`. |
+
+`boolean-method-name` takes `additionalPrefixes`, `additionalPredicates` and `additionalCommandVerbs` (string arrays)
+to widen the accepted vocabulary from a consumer config. `max-methods-per-class` takes `max`, `no-base-error` takes
+`allow`, and `require-copyright` takes `tags` to adjust their defaults.
+
+The base layer also switches on a set of built-in rules: `@typescript-eslint/no-explicit-any`, `max-lines-per-function`
+(50 lines, test code exempt) and `max-depth` (4), plus `eslint-plugin-jsdoc` rules that require a documentation comment
+on every declared function, method and class and forbid types in `@param`/`@returns` (types belong in the signature).
+The type-checked layer adds `@typescript-eslint/explicit-module-boundary-types` and
+`@typescript-eslint/only-throw-error`.
+
 ## Requirements
 
 - PHP ^8.3 (Composer package)

package/js/eslint/index.js

@@ -0,0 +1,86 @@
+import jsdoc from 'eslint-plugin-jsdoc';
+import tseslint from 'typescript-eslint';
+import plugin from './plugin.js';
+
+const TS_FILES = ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'];
+const TS_AND_JS_FILES = [...TS_FILES, '**/*.js', '**/*.jsx', '**/*.mjs', '**/*.cjs'];
+
+/**
+ * Base flat config: the AST-only custom rules that need no type information.
+ *
+ * Requires no tsconfig, so it stays cheap. The typescript-eslint parser resolves
+ * TypeScript syntax. The interface, readonly-property and enum rules target
+ * TypeScript-only constructs; no-mutable-static also applies to plain JavaScript
+ * (exported let/var, mutable static fields), so it runs across both. The opt-in
+ * type-aware layer lives in ./type-checked.js.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default [
+    {
+        files: TS_FILES,
+        plugins: {
+            '@sinemacula': plugin,
+            '@typescript-eslint': tseslint.plugin,
+        },
+        languageOptions: {
+            parser: tseslint.parser,
+        },
+        rules: {
+            '@sinemacula/no-interface-prefix': 'error',
+            '@sinemacula/require-readonly-public-property': 'error',
+            '@sinemacula/valid-enum-member-name': 'error',
+
+            '@typescript-eslint/no-explicit-any': 'error',
+        },
+    },
+    {
+        files: TS_AND_JS_FILES,
+        plugins: {
+            '@sinemacula': plugin,
+            jsdoc,
+        },
+        languageOptions: {
+            parser: tseslint.parser,
+        },
+        rules: {
+            '@sinemacula/no-mutable-static': 'error',
+            '@sinemacula/max-methods-per-class': 'error',
+            '@sinemacula/no-base-error': 'error',
+            '@sinemacula/require-copyright': 'error',
+
+            'max-lines-per-function': ['error', { max: 50, skipComments: true, skipBlankLines: true, IIFEs: true }],
+            'max-depth': ['error', 4],
+
+            // Every declared function, method, class and assigned arrow carries a
+            // documentation comment describing intent; types live in the signature,
+            // never in the comment (no @param/@returns type tags).
+            'jsdoc/require-jsdoc': ['error', {
+                require: {
+                    ClassDeclaration: true,
+                    ClassExpression: true,
+                    FunctionDeclaration: true,
+                    MethodDefinition: true,
+                },
+                contexts: [
+                    'VariableDeclarator > ArrowFunctionExpression',
+                    'VariableDeclarator > FunctionExpression',
+                ],
+                checkConstructors: false,
+            }],
+            'jsdoc/require-description': 'error',
+            'jsdoc/no-types': 'error',
+            'jsdoc/require-param-description': 'error',
+            'jsdoc/require-returns-description': 'error',
+        },
+    },
+    {
+        files: ['**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}', '**/__tests__/**', '**/tests/**'],
+        rules: {
+            'max-lines-per-function': 'off',
+            'max-depth': 'off',
+            'jsdoc/require-jsdoc': 'off',
+        },
+    },
+];

package/js/eslint/plugin.js

@@ -0,0 +1,34 @@
+import booleanMethodName from './rules/boolean-method-name.js';
+import maxMethodsPerClass from './rules/max-methods-per-class.js';
+import noBaseError from './rules/no-base-error.js';
+import noInterfacePrefix from './rules/no-interface-prefix.js';
+import noMutableStatic from './rules/no-mutable-static.js';
+import requireCopyright from './rules/require-copyright.js';
+import requireReadonlyPublicProperty from './rules/require-readonly-public-property.js';
+import validEnumMemberName from './rules/valid-enum-member-name.js';
+
+/**
+ * The @sinemacula ESLint plugin.
+ *
+ * Bundles this package's custom structural rules. Each rule is registered in
+ * the map below; the flat configs in index.js and type-checked.js are what
+ * switch them on.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default {
+    meta: {
+        name: '@sinemacula/coding-standards',
+    },
+    rules: {
+        'no-interface-prefix': noInterfacePrefix,
+        'boolean-method-name': booleanMethodName,
+        'require-readonly-public-property': requireReadonlyPublicProperty,
+        'valid-enum-member-name': validEnumMemberName,
+        'no-mutable-static': noMutableStatic,
+        'max-methods-per-class': maxMethodsPerClass,
+        'no-base-error': noBaseError,
+        'require-copyright': requireCopyright,
+    },
+};

package/js/eslint/rules/boolean-method-name.js

@@ -0,0 +1,315 @@
+import * as ts from 'typescript';
+import { ESLintUtils } from '@typescript-eslint/utils';
+import { createRule, isAmbient } from './lib.js';
+
+/** Copular and modal prefixes that read as predicates. */
+const ALLOWED_PREFIXES = new Set([
+    'is', 'are', 'was', 'were', 'has', 'have', 'had', 'can', 'could',
+    'should', 'shall', 'will', 'would', 'may', 'might', 'must', 'needs',
+    'does',
+]);
+
+/** Idiomatic predicate first words that need no is/has/can prefix. */
+const ALLOWED_PREDICATES = new Set(['successful']);
+
+/** Imperative command verbs that may return a result bool. */
+const COMMAND_VERBS = new Set([
+    'execute', 'run', 'handle', 'process', 'perform', 'persist', 'save',
+    'store', 'write', 'read', 'load', 'fetch', 'delete', 'remove', 'forget',
+    'flush', 'purge', 'clear', 'reset', 'refresh', 'sync', 'send', 'dispatch',
+    'emit', 'apply', 'guard', 'validate', 'verify', 'authorize', 'ensure',
+    'assert', 'register', 'boot', 'build', 'make', 'resolve', 'render',
+    'compute', 'calculate', 'expose', 'parse', 'format', 'transform', 'toggle',
+]);
+
+/** Matches @imperative only at a docblock tag position, never inside prose. */
+const IMPERATIVE_TAG = /^[ \t*]*@imperative(?![-\w])/im;
+
+/** The leading camelCase word of a method name. */
+function firstWord(name) {
+    const match = /^[a-z]+/.exec(name);
+
+    return match ? match[0] : '';
+}
+
+/**
+ * Whether the name reads as a predicate: a copular/modal prefix, an idiomatic
+ * predicate, or a verb ending in `s` (third-person) or `ed` (past tense).
+ */
+function isPredicate(name, prefixes, predicates) {
+    const first = firstWord(name);
+
+    return prefixes.has(first)
+        || predicates.has(first)
+        || first.endsWith('s')
+        || first.endsWith('ed');
+}
+
+/** Whether the name is an imperative command verb, not a predicate. */
+function isCommandVerb(name, verbs) {
+    return verbs.has(firstWord(name));
+}
+
+/**
+ * Whether a return type resolves to boolean, ignoring a nullable `?bool`-style
+ * null/undefined/void tail so an optional boolean still counts. Promise wrappers
+ * are unwrapped before this is called, so an awaited boolean counts too.
+ */
+function returnsBoolean(type) {
+    if (type.flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral)) {
+        return true;
+    }
+
+    if (type.isUnion()) {
+        const parts = type.types.filter(
+            part => (part.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined | ts.TypeFlags.Void)) === 0,
+        );
+
+        return parts.length > 0 && parts.every(returnsBoolean);
+    }
+
+    return false;
+}
+
+/** Whether the node is a function expression carrying an inspectable signature. */
+function isFunctionExpression(node) {
+    return node != null
+        && (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression');
+}
+
+/** The static name of a member key, or null when it is not statically named. */
+function keyName(keyNode) {
+    if (keyNode.type === 'Identifier' || keyNode.type === 'PrivateIdentifier') {
+        return keyNode.name;
+    }
+
+    if (keyNode.type === 'Literal' && typeof keyNode.value === 'string') {
+        return keyNode.value;
+    }
+
+    return null;
+}
+
+/** Peel `as`/`satisfies`/non-null wrappers off an expression to reach the value. */
+function unwrapExpression(node) {
+    let current = node;
+
+    while (
+        current
+        && (current.type === 'TSAsExpression'
+            || current.type === 'TSSatisfiesExpression'
+            || current.type === 'TSNonNullExpression')
+    ) {
+        current = current.expression;
+    }
+
+    return current;
+}
+
+/**
+ * Whether an @imperative opt-out tag precedes the member, including a docblock
+ * tucked between a decorator and the member name.
+ */
+function hasImperativeTag(sourceCode, docHost, nameNode) {
+    const before = sourceCode.getCommentsBefore(docHost).at(-1);
+
+    if (before?.type === 'Block' && IMPERATIVE_TAG.test(before.value)) {
+        return true;
+    }
+
+    if (docHost.decorators?.length) {
+        const inner = sourceCode.getCommentsBefore(nameNode).at(-1);
+
+        return inner?.type === 'Block' && IMPERATIVE_TAG.test(inner.value);
+    }
+
+    return false;
+}
+
+/**
+ * Report the name when it neither reads as a predicate nor is exempt and the
+ * resolved (awaited) return type is boolean. Type-predicate guards are predicates
+ * by structure and left alone.
+ */
+function inspect(state, nameNode, name, fnNode, docHost) {
+    const { checker, services, context, sourceCode } = state;
+
+    if (
+        name.startsWith('__')
+        || isPredicate(name, state.prefixes, state.predicates)
+        || isCommandVerb(name, state.commandVerbs)
+        || hasImperativeTag(sourceCode, docHost, nameNode)
+    ) {
+        return;
+    }
+
+    const signature = checker.getSignatureFromDeclaration(services.esTreeNodeToTSNodeMap.get(fnNode));
+
+    if (!signature || checker.getTypePredicateOfSignature(signature)) {
+        return;
+    }
+
+    const returnType = checker.getReturnTypeOfSignature(signature);
+
+    if (!returnsBoolean(checker.getAwaitedType(returnType) ?? returnType)) {
+        return;
+    }
+
+    context.report({ node: nameNode, messageId: 'notPredicate', data: { name } });
+}
+
+/**
+ * Guard a statically named function value (arrow field, object method or const
+ * binding) down to a named key, then inspect it.
+ */
+function inspectFunctionValue(state, keyNode, valueNode, docHost) {
+    const name = keyName(keyNode);
+
+    if (name !== null) {
+        inspect(state, keyNode, name, valueNode, docHost);
+    }
+}
+
+/**
+ * Guard a class member down to a statically named, non-accessor method, then
+ * inspect it. A bodiless member is dropped as an overload signature so the
+ * implementation reports once, unless it is abstract or ambient, where the
+ * bodiless declaration is the real thing to check.
+ */
+function inspectMember(state, node, allowEmptyBody) {
+    if (node.computed || node.kind !== 'method') {
+        return;
+    }
+
+    const name = keyName(node.key);
+
+    if (name === null) {
+        return;
+    }
+
+    if (!allowEmptyBody && node.value.body === null && !isAmbient(node, state.context.filename)) {
+        return;
+    }
+
+    inspect(state, node.key, name, node, node);
+}
+
+/**
+ * The visitor: inspect each named function, method, signature and function-valued
+ * member for a boolean return that does not read as a predicate.
+ */
+function buildListeners(state) {
+    return {
+        FunctionDeclaration(node) {
+            if (node.id) {
+                inspect(state, node.id, node.id.name, node, node);
+            }
+        },
+        TSDeclareFunction(node) {
+            if (node.id && isAmbient(node, state.context.filename)) {
+                inspect(state, node.id, node.id.name, node, node);
+            }
+        },
+        MethodDefinition(node) {
+            inspectMember(state, node, false);
+        },
+        TSAbstractMethodDefinition(node) {
+            inspectMember(state, node, true);
+        },
+        TSMethodSignature(node) {
+            if (!node.computed && node.kind === 'method') {
+                const name = keyName(node.key);
+
+                if (name !== null) {
+                    inspect(state, node.key, name, node, node);
+                }
+            }
+        },
+        PropertyDefinition(node) {
+            const value = unwrapExpression(node.value);
+
+            if (!node.computed && isFunctionExpression(value)) {
+                inspectFunctionValue(state, node.key, value, node);
+            }
+        },
+        Property(node) {
+            const value = unwrapExpression(node.value);
+
+            if (!node.computed && node.kind === 'init' && isFunctionExpression(value)) {
+                inspectFunctionValue(state, node.key, value, node);
+            }
+        },
+        VariableDeclarator(node) {
+            const init = unwrapExpression(node.init);
+
+            if (isFunctionExpression(init)) {
+                inspectFunctionValue(state, node.id, init, node.parent);
+            }
+        },
+    };
+}
+
+/**
+ * Boolean method name rule.
+ *
+ * A function, method, arrow-bound class field, object method or interface/type
+ * signature returning boolean should read as a predicate. A name is accepted when
+ * its first camelCase word is a copular or modal prefix (is, has, can, ...), an
+ * idiomatic predicate from ALLOWED_PREDICATES (e.g. successful), or a verb ending
+ * in `s` (third-person: permits, passes) or `ed` (past tense: succeeded, failed,
+ * expired). An imperative command verb (execute, persist, guard, ...) that returns
+ * a result bool is exempt via COMMAND_VERBS. A member may also opt out with an
+ * @imperative docblock tag. Accessors, the constructor, computed names, magic
+ * names and type-predicate guards (x is T) are exempt. The return type is resolved
+ * from type information - inferred booleans and awaited Promise<boolean> included -
+ * so the rule degrades to a no-op when no type information is available. The
+ * accepted vocabulary can be widened per consumer through the rule options.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'boolean-method-name',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require an interrogative prefix on methods and functions that return boolean.',
+        },
+        schema: [{
+            type: 'object',
+            properties: {
+                additionalPrefixes: { type: 'array', items: { type: 'string' } },
+                additionalPredicates: { type: 'array', items: { type: 'string' } },
+                additionalCommandVerbs: { type: 'array', items: { type: 'string' } },
+            },
+            additionalProperties: false,
+        }],
+        messages: {
+            notPredicate: 'Boolean method "{{ name }}" should read as a predicate (is/has/can/...).',
+        },
+    },
+    defaultOptions: [{ additionalPrefixes: [], additionalPredicates: [], additionalCommandVerbs: [] }],
+    create(context, [options]) {
+        const services = ESLintUtils.getParserServices(context, true);
+
+        // Without a type-checker program the return type can't be resolved, so
+        // the rule cannot decide anything; degrade to a no-op rather than throw.
+        if (!services.program) {
+            return {};
+        }
+
+        // Merge consumer additions onto the defaults so a downstream ruleset can
+        // widen the accepted vocabulary without losing the built-in words.
+        const state = {
+            context,
+            services,
+            sourceCode: context.sourceCode,
+            checker: services.program.getTypeChecker(),
+            prefixes: new Set([...ALLOWED_PREFIXES, ...options.additionalPrefixes]),
+            predicates: new Set([...ALLOWED_PREDICATES, ...options.additionalPredicates]),
+            commandVerbs: new Set([...COMMAND_VERBS, ...options.additionalCommandVerbs]),
+        };
+
+        return buildListeners(state);
+    },
+});

package/js/eslint/rules/lib.js

@@ -0,0 +1,90 @@
+/**
+ * Shared helpers for the @sinemacula ESLint rules.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+/** Shared rule factory linking each rule to its documentation anchor. */
+export const createRule = ESLintUtils.RuleCreator(
+    name => `https://github.com/sinemacula/coding-standards#${name}`,
+);
+
+/** Whether the file is a TypeScript declaration file (.d.ts, .d.mts, .d.cts). */
+export function isDeclarationFile(filename) {
+    return /\.d\.[cm]?ts$/.test(filename);
+}
+
+/**
+ * Whether the file path marks it as test code, widening the tests/ directory
+ * convention to the .test/.spec suffixes and the __tests__ directory.
+ */
+export function isTestPath(filename) {
+    const path = filename.replace(/\\/g, '/');
+
+    return path.includes('/tests/')
+        || path.includes('/__tests__/')
+        || /\.(test|spec)\.[cm]?[jt]sx?$/.test(path);
+}
+
+/**
+ * Whether a node sits in an ambient context: a declaration file, or inside a
+ * `declare` class, namespace or block, where a declaration describes existing
+ * shape rather than creating runtime state.
+ */
+export function isAmbient(node, filename) {
+    if (isDeclarationFile(filename)) {
+        return true;
+    }
+
+    for (let current = node; current; current = current.parent) {
+        if (current.declare === true) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/** The nearest enclosing class of a node, or null when it sits outside one. */
+export function nearestClass(ancestors) {
+    for (let i = ancestors.length - 1; i >= 0; i--) {
+        if (ancestors[i].type === 'ClassDeclaration' || ancestors[i].type === 'ClassExpression') {
+            return ancestors[i];
+        }
+    }
+
+    return null;
+}
+
+/**
+ * The simple name of a class's parent, or null when it has none or comes from a
+ * computed expression. A qualified parent (`ns.Model`) reduces to its final
+ * segment; a mixin-produced base (`mixin(Base)`) has no name.
+ */
+export function superClassName(klass) {
+    const parent = klass.superClass;
+
+    if (parent?.type === 'Identifier') {
+        return parent.name;
+    }
+
+    if (parent?.type === 'MemberExpression' && parent.property.type === 'Identifier') {
+        return parent.property.name;
+    }
+
+    return null;
+}
+
+/** Whether the class reads as a test class (by its own or its parent's name). */
+export function isTestClass(klass) {
+    if (klass.id?.name?.endsWith('Test')) {
+        return true;
+    }
+
+    const parent = superClassName(klass);
+
+    return parent !== null && parent.endsWith('TestCase');
+}