@sinemacula/coding-standards 1.11.0 → 1.12.1

package/README.md

@@ -242,10 +242,12 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 | `SineMacula.Classes.RequireReadonlyPublicProperty` | Public properties (declared or promoted) must be `readonly`. |
 | `SineMacula.Commenting.CommentLineLength` | Standalone comment lines must not exceed 80 chars (FQCN/URL exempt). |
 | `SineMacula.Commenting.ConsistentEnumCaseComments` | Enum case docs are all-or-nothing within an enum. |
+| `SineMacula.Commenting.MultilineMethodComment` | A method's doc comment must span multiple lines. |
 | `SineMacula.Commenting.RequireConstantComment` | Every class/interface/enum/trait constant needs a doc comment. |
 | `SineMacula.Commenting.RequireCopyrightTag` | Class/interface/enum/trait docblocks must carry an `@copyright` tag. |
 | `SineMacula.Commenting.RequireNonPromotedParameterComment` | Plain params mixed with promoted ones need a comment. |
 | `SineMacula.Commenting.RequirePromotedPropertyComment` | Every constructor-promoted property needs a doc comment. |
+| `SineMacula.Commenting.SingleLineMemberComment` | A property, constant or enum-case doc comment sits on one line. |
 | `SineMacula.Exceptions.DisallowBaseException` | No throwing the base `\Exception`; throw a domain exception. |
 | `SineMacula.Exceptions.RequireEmptyCatchComment` | An empty catch block must comment its intentional swallow. |
 | `SineMacula.Functions.RequireSensitiveParameter` | Secret-named params need `#[\SensitiveParameter]`. |
@@ -283,17 +285,23 @@ type-checked layer.
 | `@sinemacula/no-base-error` | Throw a domain-specific `Error` subclass, never the base `Error`; test code exempt. |
 | `@sinemacula/require-copyright` | Every file must carry a documentation comment with `@copyright` and `@author`. |
 | `@sinemacula/align-doc-tags` | `@author` and `@copyright` values line up at a single column; autofixable. |
+| `@sinemacula/single-line-property-doc` | A data member's documentation comment sits on one line; autofixable. |
+| `@sinemacula/multiline-function-doc` | A method's documentation comment spans multiple lines; autofixable. |
 
 `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. `align-doc-tags` takes `tags` and `column`,
 the column counting from the `@`, so the default of 14 gives `@author` six spaces and `@copyright` three.
+Together `single-line-property-doc` and `multiline-function-doc` set a member's comment shape by its kind: data
+members (interface property signatures, enum members and data class fields) take one line, while methods, interface
+method signatures and class fields holding a function take several. A data comment is never required, only held to
+one line where present; a free function keeps the freedom of either shape.
 
 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, forbid types in `@param`/`@returns` (the tags themselves are welcome,
-types belong in the signature) and keep a blank line above every documentation block, single-line blocks included.
-The type-checked layer adds `@typescript-eslint/explicit-module-boundary-types` and
+on every declared function, method, class, interface member and class field, forbid types in `@param`/`@returns` (the
+tags themselves are welcome, types belong in the signature) and keep a blank line above every documentation block,
+single-line blocks included. The type-checked layer adds `@typescript-eslint/explicit-module-boundary-types` and
 `@typescript-eslint/only-throw-error`.
 
 ## Requirements

package/js/eslint/index.js

@@ -50,16 +50,20 @@ export default [
             '@sinemacula/no-base-error': 'error',
             '@sinemacula/require-copyright': 'error',
             '@sinemacula/align-doc-tags': 'error',
+            '@sinemacula/single-line-property-doc': 'error',
+            '@sinemacula/multiline-function-doc': '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, so a tag never annotates one: the @param and @returns
-            // tags themselves are welcome, only their type forms are not. Each
-            // block stands off from the code above it, single-line blocks
-            // included.
+            // Every declared function, method, class, assigned arrow and
+            // property carries a documentation comment describing intent, so a
+            // reader meets each member's purpose before its type. Interface
+            // members and class fields are held to the same bar as methods.
+            // Types live in the signature, so a tag never annotates one: the
+            // @param and @returns tags themselves are welcome, only their type
+            // forms are not. Each block stands off from the code above it,
+            // single-line blocks included.
             'jsdoc/require-jsdoc': ['error', {
                 require: {
                     ClassDeclaration: true,
@@ -70,8 +74,15 @@ export default [
                 contexts: [
                     'VariableDeclarator > ArrowFunctionExpression',
                     'VariableDeclarator > FunctionExpression',
+                    'TSPropertySignature',
+                    'TSMethodSignature',
+                    'PropertyDefinition',
                 ],
                 checkConstructors: false,
+                // Report only; the autofix inserts an empty stub that then
+                // fails require-description, so a blind fix would scatter
+                // hollow comments rather than resolve the finding.
+                enableFixer: false,
             }],
             'jsdoc/require-description': 'error',
             'jsdoc/no-types': 'error',

package/js/eslint/plugin.js

@@ -1,11 +1,13 @@
 import alignDocTags from './rules/align-doc-tags.js';
 import booleanMethodName from './rules/boolean-method-name.js';
 import maxMethodsPerClass from './rules/max-methods-per-class.js';
+import multilineFunctionDoc from './rules/multiline-function-doc.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 singleLinePropertyDoc from './rules/single-line-property-doc.js';
 import validEnumMemberName from './rules/valid-enum-member-name.js';
 
 /**
@@ -32,5 +34,7 @@ export default {
         'no-base-error': noBaseError,
         'require-copyright': requireCopyright,
         'align-doc-tags': alignDocTags,
+        'single-line-property-doc': singleLinePropertyDoc,
+        'multiline-function-doc': multilineFunctionDoc,
     },
 };

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

@@ -20,8 +20,12 @@ const COMMAND_VERBS = new Set([
     'emit', 'apply', 'guard', 'validate', 'verify', 'authorize', 'ensure',
     'assert', 'register', 'boot', 'build', 'make', 'resolve', 'render',
     'compute', 'calculate', 'expose', 'parse', 'format', 'transform', 'toggle',
+    'submit', 'confirm', 'copy', 'attempt',
 ]);
 
+/** Method names that are a primitive type keyword: typed accessors, not predicates. */
+const TYPE_ACCESSOR_NAMES = new Set(['boolean']);
+
 /** Matches @imperative only at a docblock tag position, never inside prose. */
 const IMPERATIVE_TAG = /^[ \t*]*@imperative(?![-\w])/im;
 
@@ -50,6 +54,11 @@ function isCommandVerb(name, verbs) {
     return verbs.has(firstWord(name));
 }
 
+/** Whether the name is an on* event-handler callback (onError, onUnauthorized). */
+function isEventHandler(name) {
+    return /^on[A-Z]/.test(name);
+}
+
 /**
  * Whether a return type resolves to boolean, ignoring a nullable `?bool`-style
  * null/undefined/void tail so an optional boolean still counts. Promise
@@ -143,6 +152,8 @@ function inspect(state, nameNode, name, fnNode, docHost) {
         name.startsWith('__')
         || isPredicate(name, state.prefixes, state.predicates)
         || isCommandVerb(name, state.commandVerbs)
+        || isEventHandler(name)
+        || TYPE_ACCESSOR_NAMES.has(name)
         || hasImperativeTag(sourceCode, docHost, nameNode)
     ) {
         return;
@@ -266,8 +277,10 @@ function buildListeners(state) {
  * 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
+ * @imperative docblock tag. An on* event-handler callback (onError) and a
+ * method named after a primitive type (a typed accessor such as boolean())
+ * are exempt, as are accessors, the constructor, computed names, magic names
+ * and type-predicate guards (x is T). 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

package/js/eslint/rules/multiline-function-doc.js

@@ -0,0 +1,103 @@
+import { createRule } from './lib.js';
+
+/** Values that make a class field read as behaviour rather than data. */
+const FUNCTION_VALUES = new Set(['ArrowFunctionExpression', 'FunctionExpression']);
+
+/**
+ * Whether the node declares a method or a method-like member: a class method,
+ * an interface method signature, or a class field that holds a function.
+ */
+function isMethodMember(node) {
+    switch (node.type) {
+        case 'MethodDefinition':
+        case 'TSAbstractMethodDefinition':
+        case 'TSMethodSignature':
+            return true;
+        case 'PropertyDefinition':
+            return Boolean(node.value) && FUNCTION_VALUES.has(node.value.type);
+        default:
+            return false;
+    }
+}
+
+/** The single line of prose a one-line documentation block carries. */
+function singleLineContent(value) {
+    return value.replace(/^\*/, '').trim();
+}
+
+/**
+ * Require a method's documentation comment to span multiple lines.
+ *
+ * A method earns a fuller account than a data field: what it does, and in time
+ * its parameters and what it returns. Holding its comment open across lines
+ * keeps that room ready and sets behaviour apart from data at a glance, the
+ * mirror of the single-line form data properties take. Class methods, interface
+ * method signatures and class fields that hold a function are governed; a data
+ * property keeps its one line, and a free function is left to the author, since
+ * a short helper reads well on a single line.
+ *
+ * A block already spanning lines passes. A one-line block is unfolded onto
+ * three, its prose moved to the middle line; an empty one is left for the
+ * description rule to report, since there is nothing to unfold.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'multiline-function-doc',
+    meta: {
+        type: 'layout',
+        fixable: 'whitespace',
+        docs: {
+            description: 'Require a method documentation comment to span multiple lines.',
+        },
+        schema: [],
+        messages: {
+            singleLine: 'A method documentation comment must span multiple lines.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const { sourceCode } = context;
+
+        /** Unfold a method's one-line documentation block onto three lines. */
+        function inspect(node) {
+            if (!isMethodMember(node)) {
+                return;
+            }
+
+            const doc = sourceCode.getCommentsBefore(node).at(-1);
+
+            if (!doc || doc.type !== 'Block' || !doc.value.startsWith('*')) {
+                return;
+            }
+
+            if (doc.loc.start.line !== doc.loc.end.line) {
+                return;
+            }
+
+            const content = singleLineContent(doc.value);
+
+            // An empty block is the description rule's to report; there is no
+            // prose to move onto the middle line.
+            if (content.length === 0) {
+                return;
+            }
+
+            const pad = ' '.repeat(doc.loc.start.column);
+
+            context.report({
+                node: doc,
+                messageId: 'singleLine',
+                fix: fixer => fixer.replaceText(doc, `/**\n${pad} * ${content}\n${pad} */`),
+            });
+        }
+
+        return {
+            MethodDefinition: inspect,
+            TSAbstractMethodDefinition: inspect,
+            TSMethodSignature: inspect,
+            PropertyDefinition: inspect,
+        };
+    },
+});

package/js/eslint/rules/single-line-property-doc.js

@@ -0,0 +1,107 @@
+import { createRule } from './lib.js';
+
+/** Class-field values that read as behaviour rather than data. */
+const FUNCTION_VALUES = new Set(['ArrowFunctionExpression', 'FunctionExpression']);
+
+/**
+ * Whether the node is a data member: an interface property signature, an enum
+ * member, or a class field that does not hold a function.
+ */
+function isDataProperty(node) {
+    if (node.type === 'TSPropertySignature' || node.type === 'TSEnumMember') {
+        return true;
+    }
+
+    return node.type === 'PropertyDefinition'
+        && !(node.value && FUNCTION_VALUES.has(node.value.type));
+}
+
+/**
+ * The text lines a documentation block carries, each stripped of its leading
+ * margin and asterisk, with blank lines dropped.
+ */
+function contentLines(value) {
+    return value
+        .split('\n')
+        .map(line => line.replace(/^\s*\*?[^\S\n]?/, '').trimEnd())
+        .filter(line => line.length > 0);
+}
+
+/**
+ * Require a data member's documentation comment to sit on a single line.
+ *
+ * A field's description is a single phrase, so it belongs on one line however
+ * long it runs; nothing wraps a comment to a width, and breaking it by hand
+ * only scatters the phrase down the file. Interface property signatures, enum
+ * members and class fields that hold data are governed; a class field holding a
+ * function reads as behaviour, may document parameters and is left to span as
+ * many lines as it needs, as are methods and every free function. A comment is
+ * never required here, only held to one line where it is present, so enum
+ * members stay documented at the author's discretion.
+ *
+ * A block already on one line passes. A multi-line block collapses to one, its
+ * lines joined by single spaces, provided it carries prose alone: a block
+ * bearing a tag such as `@deprecated` keeps its shape and is reported without a
+ * fix, since folding a tag into a running line would change its meaning.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'single-line-property-doc',
+    meta: {
+        type: 'layout',
+        fixable: 'whitespace',
+        docs: {
+            description: 'Require a data member documentation comment to sit on a single line.',
+        },
+        schema: [],
+        messages: {
+            multiline: 'A data member documentation comment must sit on a single line.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const { sourceCode } = context;
+
+        /** Fold a data property's leading documentation block onto one line. */
+        function inspect(node) {
+            if (!isDataProperty(node)) {
+                return;
+            }
+
+            const comments = sourceCode.getCommentsBefore(node);
+            const doc = comments.at(-1);
+
+            if (!doc || doc.type !== 'Block' || !doc.value.startsWith('*')) {
+                return;
+            }
+
+            if (doc.loc.start.line === doc.loc.end.line) {
+                return;
+            }
+
+            const lines = contentLines(doc.value);
+
+            // An empty block is the description rule's to report; there is no
+            // prose to fold onto one line.
+            if (lines.length === 0) {
+                return;
+            }
+
+            const hasTag = lines.some(line => line.startsWith('@'));
+
+            context.report({
+                node: doc,
+                messageId: 'multiline',
+                fix: hasTag ? null : fixer => fixer.replaceText(doc, `/** ${lines.join(' ')} */`),
+            });
+        }
+
+        return {
+            TSPropertySignature: inspect,
+            TSEnumMember: inspect,
+            PropertyDefinition: inspect,
+        };
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sinemacula/coding-standards",
-    "version": "1.11.0",
+    "version": "1.12.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>",