@sinemacula/coding-standards 1.8.4 → 1.9.1

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;
+}

package/js/eslint/rules/valid-enum-member-name.js

@@ -0,0 +1,46 @@
+import { createRule } from './lib.js';
+
+/** The pattern a valid enum member name must match. */
+const NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * Enum member naming rule.
+ *
+ * Ensures every enum member is declared in SCREAMING_SNAKE_CASE, matching the
+ * Sine Macula house convention for enum members. Only real `enum` declarations
+ * are checked; object-literal "as const" pseudo-enums are out of scope.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'valid-enum-member-name',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require enum members to be declared in SCREAMING_SNAKE_CASE.',
+        },
+        schema: [],
+        messages: {
+            notUpperSnakeCase: 'Enum member "{{ name }}" must be declared in SCREAMING_SNAKE_CASE.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        // Only enum members are visited; a switch `case` is a SwitchCase node
+        // and never reaches this visitor.
+        return {
+            TSEnumMember(node) {
+                const id = node.id;
+                // A member name is either a bare identifier or a string literal;
+                // a string literal is checked by its resolved value, not the raw
+                // source text.
+                const name = id.type === 'Identifier' ? id.name : String(id.value);
+
+                if (!NAME_PATTERN.test(name)) {
+                    context.report({ node: id, messageId: 'notUpperSnakeCase', data: { name } });
+                }
+            },
+        };
+    },
+});

package/js/eslint/type-checked.js

@@ -0,0 +1,41 @@
+import tseslint from 'typescript-eslint';
+import base from './index.js';
+import plugin from './plugin.js';
+
+/**
+ * Opt-in type-aware layer: the cross-file and type-driven rules. Spreads the
+ * base config, then turns on type information via the project service so the
+ * type-aware custom rules and the curated typescript-eslint rules can resolve.
+ * Layered on only where a consumer tsconfig exists, keeping the base config the
+ * cheap fast path.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default [
+    ...base,
+    {
+        files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
+        plugins: {
+            '@sinemacula': plugin,
+            '@typescript-eslint': tseslint.plugin,
+        },
+        languageOptions: {
+            parser: tseslint.parser,
+            parserOptions: {
+                projectService: true,
+            },
+        },
+        rules: {
+            '@sinemacula/boolean-method-name': 'error',
+
+            '@typescript-eslint/await-thenable': 'error',
+            '@typescript-eslint/consistent-type-imports': 'error',
+            '@typescript-eslint/explicit-module-boundary-types': 'error',
+            '@typescript-eslint/no-floating-promises': 'error',
+            '@typescript-eslint/no-misused-promises': 'error',
+            '@typescript-eslint/only-throw-error': 'error',
+            // '@typescript-eslint/strict-boolean-expressions': 'error',
+        },
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sinemacula/coding-standards",
-    "version": "1.8.4",
+    "version": "1.9.1",
     "description": "Centralized coding standards, static analysis configurations, and code quality tooling for all Sine Macula repositories.",
     "license": "Apache-2.0",
     "author": "Ben Carey <bdmc@sinemacula.co.uk>",
@@ -15,10 +15,12 @@
     "keywords": [
         "biome",
         "knip",
+        "eslint",
         "coding-standards",
         "linting",
         "config"
     ],
+    "type": "module",
     "files": [
         "js/",
         "markdown/",
@@ -27,8 +29,47 @@
         "security/",
         "README.md",
         "LICENSE",
-        "NOTICE"
+        "NOTICE",
+        "!js/eslint/rules/__tests__"
     ],
+    "exports": {
+        "./js/eslint": "./js/eslint/index.js",
+        "./js/eslint/type-checked": "./js/eslint/type-checked.js",
+        "./*": "./*"
+    },
+    "scripts": {
+        "test:js": "vitest run",
+        "lint:js": "eslint js/eslint"
+    },
+    "devDependencies": {
+        "@typescript-eslint/rule-tester": "^8.0.0",
+        "@typescript-eslint/utils": "^8.0.0",
+        "eslint": "^9.0.0",
+        "eslint-plugin-jsdoc": "^63.0.13",
+        "typescript": "^5.0.0",
+        "typescript-eslint": "^8.0.0",
+        "vitest": "^3.0.0"
+    },
+    "peerDependencies": {
+        "eslint": ">=9",
+        "eslint-plugin-jsdoc": ">=48",
+        "typescript": ">=4.8.4",
+        "typescript-eslint": "^8"
+    },
+    "peerDependenciesMeta": {
+        "eslint": {
+            "optional": true
+        },
+        "eslint-plugin-jsdoc": {
+            "optional": true
+        },
+        "typescript": {
+            "optional": true
+        },
+        "typescript-eslint": {
+            "optional": true
+        }
+    },
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"