@sinemacula/coding-standards 1.8.3 → 1.9.0

package/js/eslint/rules/max-methods-per-class.js

@@ -0,0 +1,92 @@
+import { createRule, isTestClass, isTestPath } from './lib.js';
+
+/** Whether a class member counts towards the method total. */
+function isCountedMethod(member) {
+    // An overload signature shares its name with the implementation below it, so it
+    // carries no body and is not counted a second time.
+    return member.type === 'MethodDefinition'
+        && member.value.type !== 'TSEmptyBodyFunctionExpression';
+}
+
+/** The number of methods declared directly on the class body. */
+function countMethods(node) {
+    let count = 0;
+
+    for (const member of node.body.body) {
+        if (isCountedMethod(member)) {
+            count++;
+        }
+    }
+
+    return count;
+}
+
+/**
+ * Cap the number of methods declared directly on a single class.
+ *
+ * A class that grows past the limit is doing too many jobs and should be split.
+ * Every method declared on the class body counts, including the constructor,
+ * static methods and get/set accessors; a method spread across overload
+ * signatures counts once, through its implementation. Methods on a nested class
+ * belong to that class, not the one enclosing it. Test code legitimately gathers
+ * many methods on one fixture, so a test file or test class is exempt.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'max-methods-per-class',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Limit the number of methods declared on a single class.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: { type: 'integer', minimum: 0 },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            tooMany: 'Class declares {{ count }} methods; the maximum is {{ max }}.',
+        },
+    },
+    defaultOptions: [{ max: 20 }],
+    create(context, [options]) {
+        const { max }        = options;
+        const { sourceCode } = context;
+
+        if (isTestPath(context.filename)) {
+            return {};
+        }
+
+        /** Flag a class whose method count runs past the configured maximum. */
+        const inspect = node => {
+            if (isTestClass(node)) {
+                return;
+            }
+
+            const count = countMethods(node);
+
+            if (count <= max) {
+                return;
+            }
+
+            const target = node.id ?? sourceCode.getFirstToken(node, { filter: token => token.value === 'class' });
+
+            context.report({
+                loc: target.loc,
+                messageId: 'tooMany',
+                data: { count, max },
+            });
+        };
+
+        return {
+            ClassDeclaration: inspect,
+            ClassExpression: inspect,
+        };
+    },
+});

package/js/eslint/rules/no-base-error.js

@@ -0,0 +1,113 @@
+import { createRule } from './lib.js';
+
+/** Global objects whose `Error` member resolves to the base `Error`. */
+const GLOBAL_OBJECTS = new Set(['globalThis', 'window', 'global', 'self']);
+
+/** Strips the `as`, `satisfies` and non-null wrappers a throw argument may carry. */
+function unwrapType(node) {
+    let current = node;
+
+    while (
+        current.type === 'TSAsExpression'
+        || current.type === 'TSSatisfiesExpression'
+        || current.type === 'TSNonNullExpression'
+    ) {
+        current = current.expression;
+    }
+
+    return current;
+}
+
+/** Whether a node is a reference to one of the recognised global objects. */
+function isGlobalObjectRef(node) {
+    return node.type === 'Identifier' && GLOBAL_OBJECTS.has(node.name);
+}
+
+/** Whether a node is the identifier `Error`. */
+function isErrorProperty(node) {
+    return node.type === 'Identifier' && node.name === 'Error';
+}
+
+/** Whether a member expression reads as `<global>.Error`. */
+function isGlobalError(callee) {
+    return callee.type === 'MemberExpression'
+        && !callee.computed
+        && isGlobalObjectRef(callee.object)
+        && isErrorProperty(callee.property);
+}
+
+/** Whether a construction callee denotes the base `Error`, directly or through a global object. */
+function isBaseError(callee) {
+    if (callee.type === 'Identifier') {
+        return callee.name === 'Error';
+    }
+
+    return isGlobalError(callee);
+}
+
+/**
+ * Disallow throwing the base `Error`.
+ *
+ * A bare `throw new Error(...)`, including the argument-free `throw new Error`,
+ * gives a caller no type to catch on, so a domain-specific subclass such as
+ * `ValidationError` must be thrown instead.
+ *
+ * The check is syntactic. It flags a throw whose argument constructs the base
+ * `Error`, whether named directly (`new Error()`) or reached through a global
+ * object (`new globalThis.Error()`, `new window.Error()`). A `throw ... as X`,
+ * `throw ...!` or `satisfies` annotation is unwrapped before the construction is
+ * inspected, so the annotation cannot hide the throw. Subclasses
+ * (`new NotFoundError()`) and the specific built-ins (`new TypeError()`) read as
+ * domain-specific and pass; a re-thrown variable (`throw err`), a qualified name
+ * (`new foo.Error()`) and a base `Error` built for a non-throw use
+ * (`const e = new Error()`) fall outside the pattern. Only the base `Error` is
+ * ever a candidate, so listing `Error` in the `allow` option is the one way to
+ * permit it; any other name has nothing to match and stays inert.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'no-base-error',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow throwing the base Error in favour of a domain-specific subclass.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allow: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            baseError: 'Throw a domain-specific Error subclass, not the base Error.',
+        },
+    },
+    defaultOptions: [{ allow: [] }],
+    create(context, [options]) {
+        const allow = options.allow ?? [];
+
+        return {
+            ThrowStatement(node) {
+                const thrown = unwrapType(node.argument);
+
+                if (thrown.type !== 'NewExpression' || !isBaseError(thrown.callee)) {
+                    return;
+                }
+
+                if (allow.includes('Error')) {
+                    return;
+                }
+
+                context.report({ node: thrown, messageId: 'baseError' });
+            },
+        };
+    },
+});

package/js/eslint/rules/no-interface-prefix.js

@@ -0,0 +1,55 @@
+import { createRule } from './lib.js';
+
+/** Disallowed "I" prefix: a capital I directly followed by another uppercase letter. */
+const PREFIX_PATTERN = /^I[A-Z]/;
+
+/** A global or string-named module block augments types we do not own. */
+const isExternalAugmentation = node =>
+    node.type === 'TSModuleDeclaration'
+    && (node.kind === 'global' || node.id.type === 'Literal');
+
+/**
+ * Forbids the Hungarian "I" prefix on interface and type-alias names
+ * (IUserRepository), which adds nothing over the language's own type system.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'no-interface-prefix',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow the "I" prefix on interface and type-alias names.',
+        },
+        schema: [],
+        messages: {
+            prefixed: '{{ kind }} "{{ name }}" must not use an "I" prefix.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const { sourceCode } = context;
+
+        /** Report a declaration whose name carries the disallowed "I" prefix. */
+        const check = (node, kind) => {
+            const name = node.id.name;
+
+            if (!PREFIX_PATTERN.test(name)) {
+                return;
+            }
+
+            // Augmenting an external module or the global scope cannot rename it.
+            if (sourceCode.getAncestors(node).some(isExternalAugmentation)) {
+                return;
+            }
+
+            context.report({ node: node.id, messageId: 'prefixed', data: { kind, name } });
+        };
+
+        return {
+            TSInterfaceDeclaration: node => check(node, 'Interface'),
+            TSTypeAliasDeclaration: node => check(node, 'Type'),
+        };
+    },
+});

package/js/eslint/rules/no-mutable-static.js

@@ -0,0 +1,213 @@
+import { ASTUtils } from '@typescript-eslint/utils';
+import { createRule, isAmbient, isDeclarationFile, isTestClass, isTestPath, nearestClass } from './lib.js';
+
+/** Unwrap a rest element to its bound target, else return the node unchanged. */
+function restTarget(node) {
+    return node.type === 'RestElement' ? node.argument : node;
+}
+
+/** The destructuring children of a pattern that may bind further identifiers. */
+function patternChildren(pattern) {
+    switch (pattern.type) {
+        case 'ArrayPattern':
+            return pattern.elements.filter(Boolean).map(restTarget);
+        case 'ObjectPattern':
+            return pattern.properties.map(
+                property => (property.type === 'RestElement' ? property.argument : property.value),
+            );
+        case 'AssignmentPattern':
+            return [pattern.left];
+        default:
+            return [];
+    }
+}
+
+/** Collect the bound identifiers of a declarator target, unwrapping destructuring. */
+function boundIdentifiers(pattern, out) {
+    if (pattern.type === 'Identifier') {
+        out.push(pattern);
+        return;
+    }
+
+    for (const child of patternChildren(pattern)) {
+        boundIdentifiers(child, out);
+    }
+}
+
+/**
+ * Whether a resolved binding is a mutable local `let`/`var` (not const, class,
+ * function, import or an ambient declaration), and so publishes live module state.
+ */
+function bindsMutableVariable(variable, filename) {
+    if (isDeclarationFile(filename)) {
+        return false;
+    }
+
+    return variable.defs.some(
+        def => def.type === 'Variable' && def.parent.declare !== true && def.parent.kind !== 'const',
+    );
+}
+
+/** Matches @managed-static only at a docblock tag position, never inside prose. */
+const MANAGED_TAG = /(?:^|[\s*])@managed-static(?![-\w])/i;
+
+/**
+ * Whether a @managed-static opt-out docblock precedes the node, including one
+ * tucked between a decorator and the member name.
+ */
+function hasManagedTag(node, sourceCode) {
+    const before = sourceCode.getCommentsBefore(node).at(-1);
+
+    if (before?.type === 'Block' && MANAGED_TAG.test(before.value)) {
+        return true;
+    }
+
+    // A docblock tucked between the decorators and the declaration sits before the
+    // first token after the last decorator, not before the whole member.
+    if (node.decorators?.length) {
+        const afterDecorators = sourceCode.getTokenAfter(node.decorators.at(-1));
+        const inner = afterDecorators && sourceCode.getCommentsBefore(afterDecorators).at(-1);
+
+        return inner?.type === 'Block' && MANAGED_TAG.test(inner.value);
+    }
+
+    return false;
+}
+
+/** A readable name for a class member key, including private and computed forms. */
+function describeKey(node, sourceCode) {
+    if (node.computed) {
+        return `[${sourceCode.getText(node.key)}]`;
+    }
+
+    if (node.key.type === 'PrivateIdentifier') {
+        return `#${node.key.name}`;
+    }
+
+    if (node.key.type === 'Literal') {
+        return String(node.key.value);
+    }
+
+    return node.key.name;
+}
+
+/** Report each identifier bound by an inline `export let`/`export var` declaration. */
+function reportInlineExports(node, context) {
+    const declaration = node.declaration;
+
+    if (declaration.type !== 'VariableDeclaration' || declaration.kind === 'const') {
+        return;
+    }
+
+    if (isAmbient(declaration, context.filename)) {
+        return;
+    }
+
+    const identifiers = [];
+
+    for (const declarator of declaration.declarations) {
+        boundIdentifiers(declarator.id, identifiers);
+    }
+
+    for (const identifier of identifiers) {
+        context.report({ node: identifier, messageId: 'mutableExport', data: { name: identifier.name } });
+    }
+}
+
+/** Report `export { x }` specifiers that publish a mutable local binding. */
+function reportSpecifierExports(node, context) {
+    // A re-export carries no local binding; a type-only export carries no runtime one.
+    if (node.source || node.exportKind === 'type') {
+        return;
+    }
+
+    const scope = context.sourceCode.getScope(node);
+
+    for (const specifier of node.specifiers) {
+        if (specifier.exportKind === 'type' || specifier.local.type !== 'Identifier') {
+            continue;
+        }
+
+        const variable = ASTUtils.findVariable(scope, specifier.local);
+
+        if (variable && bindsMutableVariable(variable, context.filename)) {
+            context.report({ node: specifier.local, messageId: 'mutableExport', data: { name: specifier.local.name } });
+        }
+    }
+}
+
+/**
+ * Forbids mutable module-level and class-level static state: exported `let`/`var`
+ * bindings (declared inline or published through an `export { ... }` specifier)
+ * and non-readonly `static` class fields, including `static accessor`
+ * auto-accessors. All are global mutable state; `const` and `readonly` express the
+ * read-only configuration this allows.
+ *
+ * The check is syntactic, not write-sensitive: a static is flagged whether or not
+ * a reassignment is visible, since cross-file writes are out of a per-file rule's
+ * reach. Deliberately mutated statics opt out with a `@managed-static` doc tag on
+ * the field or its declaring class, and test classes are exempt. Module scope is
+ * limited to exported bindings; an unexported module `let` stays local and is left
+ * alone.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'no-mutable-static',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow mutable exported bindings and mutable static class fields.',
+        },
+        schema: [],
+        messages: {
+            mutableExport: 'Exported binding "{{ name }}" introduces mutable module state; declare it with const.',
+            mutableStatic: 'Static field "{{ name }}" is mutable static state; mark it readonly or use a constant.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const { sourceCode } = context;
+
+        /** Whether a static member is exempt: test code or an opted-out declaration. */
+        const isStaticExempt = node => {
+            if (isTestPath(context.filename)) {
+                return true;
+            }
+
+            const klass = nearestClass(sourceCode.getAncestors(node));
+
+            if (klass !== null && isTestClass(klass)) {
+                return true;
+            }
+
+            return hasManagedTag(node, sourceCode) || (klass !== null && hasManagedTag(klass, sourceCode));
+        };
+
+        /** Flag a non-readonly static field or auto-accessor as mutable static state. */
+        const inspectStatic = node => {
+            if (!node.static || node.readonly || isAmbient(node, context.filename) || isStaticExempt(node)) {
+                return;
+            }
+
+            context.report({
+                node: node.key,
+                messageId: 'mutableStatic',
+                data: { name: describeKey(node, sourceCode) },
+            });
+        };
+
+        return {
+            ExportNamedDeclaration(node) {
+                if (node.declaration) {
+                    reportInlineExports(node, context);
+                } else {
+                    reportSpecifierExports(node, context);
+                }
+            },
+            PropertyDefinition: inspectStatic,
+            AccessorProperty: inspectStatic,
+        };
+    },
+});

package/js/eslint/rules/require-copyright.js

@@ -0,0 +1,73 @@
+import { createRule } from './lib.js';
+
+const DEFAULT_TAGS = ['copyright', 'author'];
+
+/** A boundary-anchored matcher for a documentation tag by its bare name. */
+function tagMatcher(tag) {
+    const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+    return new RegExp(`(?:^|[\\s*])@${escaped}(?![-\\w])`, 'i');
+}
+
+/**
+ * Require a documentation comment carrying the tags every source file must
+ * declare, `@copyright` and `@author` by default.
+ *
+ * A single block comment must carry all of the required tags together, so they
+ * sit inside the file's descriptive docblock alongside its summary rather than
+ * in a separate header. Only the presence of each tag is checked, never its
+ * value or alignment, which are matters of formatting. The required set is
+ * configurable, so a project may drop `@author` or add tags of its own.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'require-copyright',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require a documentation comment carrying the copyright and author tags.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missing: 'A documentation comment must carry the {{ tags }} tags.',
+        },
+    },
+    defaultOptions: [{ tags: DEFAULT_TAGS }],
+    create(context, [options]) {
+        const { sourceCode } = context;
+        const required = options.tags ?? DEFAULT_TAGS;
+        const matchers = required.map(tagMatcher);
+
+        return {
+            Program(node) {
+                const documented = sourceCode.getAllComments().some(
+                    comment => comment.type === 'Block' && matchers.every(matcher => matcher.test(comment.value)),
+                );
+
+                if (documented) {
+                    return;
+                }
+
+                context.report({
+                    node,
+                    loc: { line: 1, column: 0 },
+                    messageId: 'missing',
+                    data: { tags: required.map(tag => `@${tag}`).join(', ') },
+                });
+            },
+        };
+    },
+});

package/js/eslint/rules/require-readonly-public-property.js

@@ -0,0 +1,154 @@
+import {
+    createRule,
+    isAmbient,
+    isDeclarationFile,
+    isTestClass,
+    isTestPath,
+    nearestClass,
+    superClassName,
+} from './lib.js';
+
+/**
+ * Require the `readonly` modifier on public class properties.
+ *
+ * Public properties, whether declared or constructor-promoted, must be
+ * `readonly`. Mutable public state breaks encapsulation; the legitimate
+ * data-holder case is expressed with `public readonly`. Public auto-accessors
+ * have no `readonly` form and always expose a setter, so they are disallowed
+ * outright. Static properties are left to the mutable static state concern,
+ * non-public properties are unaffected, and ambient declarations plus test
+ * fixtures are exempt. TypeScript has no whole-class readonly modifier, so
+ * there is no class-level exemption.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'require-readonly-public-property',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require the readonly modifier on public class properties.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    ignoredParentClasses: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            mutable: 'Public property "{{ name }}" must be readonly; mutable public state breaks encapsulation.',
+            accessor: 'Public auto-accessor "{{ name }}" is mutable; make it non-public or a readonly property.',
+        },
+    },
+    defaultOptions: [{ ignoredParentClasses: [] }],
+    create(context, [options]) {
+        const ignoredParents = options.ignoredParentClasses ?? [];
+        const { sourceCode }  = context;
+
+        // Declaration files and test directories are exempt wholesale.
+        if (isDeclarationFile(context.filename) || isTestPath(context.filename)) {
+            return {};
+        }
+
+        /** Whether the node's enclosing class is exempt from the mandate. */
+        const isExempt = node => {
+            if (isAmbient(node, context.filename)) {
+                return true;
+            }
+
+            const klass = nearestClass(sourceCode.getAncestors(node));
+
+            return klass !== null
+                && (isTestClass(klass) || isIgnoredParent(klass, ignoredParents));
+        };
+
+        return {
+            'PropertyDefinition, TSAbstractPropertyDefinition'(node) {
+                if (isOutOfScope(node) || node.readonly || isExempt(node)) {
+                    return;
+                }
+
+                context.report({
+                    node: node.key,
+                    messageId: 'mutable',
+                    data: { name: propertyName(node.key, sourceCode) },
+                });
+            },
+            'AccessorProperty, TSAbstractAccessorProperty'(node) {
+                // An auto-accessor cannot be readonly, so a public one is always mutable.
+                if (isOutOfScope(node) || isExempt(node)) {
+                    return;
+                }
+
+                context.report({
+                    node: node.key,
+                    messageId: 'accessor',
+                    data: { name: propertyName(node.key, sourceCode) },
+                });
+            },
+            TSParameterProperty(node) {
+                if (node.readonly || node.accessibility !== 'public' || isExempt(node)) {
+                    return;
+                }
+
+                context.report({
+                    node: node.parameter,
+                    messageId: 'mutable',
+                    data: { name: parameterName(node.parameter) },
+                });
+            },
+        };
+    },
+});
+
+/** Whether the property's accessibility marks it non-public. */
+function isNonPublic(node) {
+    return node.key.type === 'PrivateIdentifier'
+        || node.accessibility === 'private'
+        || node.accessibility === 'protected';
+}
+
+/** Whether a class property is outside the public-mutable scope: static, ambient, or non-public. */
+function isOutOfScope(node) {
+    return node.static || node.declare || isNonPublic(node);
+}
+
+/** Whether the class extends one of the configured exempt parents. */
+function isIgnoredParent(klass, ignoredParents) {
+    const parent = superClassName(klass);
+
+    return parent !== null && ignoredParents.includes(parent);
+}
+
+/** A readable name for a (possibly computed) property key. */
+function propertyName(key, sourceCode) {
+    if (key.type === 'Identifier') {
+        return key.name;
+    }
+
+    if (key.type === 'Literal') {
+        return String(key.value);
+    }
+
+    return sourceCode.getText(key);
+}
+
+/** The declared name of a constructor parameter property. */
+function parameterName(parameter) {
+    if (parameter.type === 'Identifier') {
+        return parameter.name;
+    }
+
+    if (parameter.type === 'AssignmentPattern' && parameter.left.type === 'Identifier') {
+        return parameter.left.name;
+    }
+
+    return null;
+}