@sinemacula/coding-standards 1.10.0 → 1.12.0

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]`. |
@@ -282,15 +284,26 @@ type-checked layer.
 | `@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`; 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/pad-block-start` | An interface, class or enum body opens with a blank line; 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.
+`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.
+`pad-block-start` governs the opening brace only, leaving the closing brace against the final member. 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 and forbid types in `@param`/`@returns` (types belong in the signature).
-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

@@ -49,13 +49,22 @@ export default [
             '@sinemacula/max-methods-per-class': 'error',
             '@sinemacula/no-base-error': 'error',
             '@sinemacula/require-copyright': 'error',
+            '@sinemacula/align-doc-tags': 'error',
+            '@sinemacula/pad-block-start': '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, never in the comment (no @param/@returns type tags).
+            // 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,
@@ -66,13 +75,21 @@ 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',
             'jsdoc/require-param-description': 'error',
             'jsdoc/require-returns-description': 'error',
+            'jsdoc/lines-before-block': ['error', { lines: 1, ignoreSingleLines: false }],
         },
     },
     {

package/js/eslint/plugin.js

@@ -1,10 +1,14 @@
+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 padBlockStart from './rules/pad-block-start.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';
 
 /**
@@ -30,5 +34,9 @@ export default {
         'max-methods-per-class': maxMethodsPerClass,
         'no-base-error': noBaseError,
         'require-copyright': requireCopyright,
+        'align-doc-tags': alignDocTags,
+        'pad-block-start': padBlockStart,
+        'single-line-property-doc': singleLinePropertyDoc,
+        'multiline-function-doc': multilineFunctionDoc,
     },
 };

package/js/eslint/rules/align-doc-tags.js

@@ -0,0 +1,125 @@
+import { createRule } from './lib.js';
+
+const DEFAULT_TAGS = ['author', 'copyright'];
+const DEFAULT_COLUMN = 14;
+
+/** A documentation line opening a tag that carries a value. */
+const TAG_LINE = /^(\s*\*\s*)@([A-Za-z][\w-]*)([^\S\n]+)(?=\S)/;
+
+/**
+ * The spaces that place a tag's value at the target column, or null when the
+ * tag is too long to reach it.
+ */
+function padding(tag, column) {
+    const spaces = column - tag.length - 2;
+
+    return spaces > 0 ? ' '.repeat(spaces) : null;
+}
+
+/**
+ * Align the values of the documentation tags a file's header declares,
+ * `@author` and `@copyright` by default.
+ *
+ * The tags a file must carry read as a block, so their values line up at a
+ * single column rather than sitting at whatever offset each tag's own length
+ * happens to produce. The column counts from the `@`, which at the default of
+ * 14 gives `@author` six spaces and `@copyright` three.
+ *
+ * Only the run of whitespace between a listed tag and its value is considered,
+ * and only on the line the tag opens; a wrapped value's continuation lines, a
+ * tag with no value and every unlisted tag are left alone. A tag longer than
+ * the column can accommodate is skipped rather than reported, as no spacing
+ * would satisfy the requirement. Presence of the tags is a separate concern,
+ * enforced by `require-copyright`.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'align-doc-tags',
+    meta: {
+        type: 'layout',
+        fixable: 'whitespace',
+        docs: {
+            description: 'Align the values of the documentation tags a file header declares.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    column: {
+                        type: 'integer',
+                        minimum: 1,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            misaligned: 'The @{{ tag }} value must start at column {{ column }}.',
+        },
+    },
+    defaultOptions: [{ tags: DEFAULT_TAGS, column: DEFAULT_COLUMN }],
+    create(context, [options]) {
+        const { sourceCode } = context;
+        const tags = new Set((options.tags ?? DEFAULT_TAGS).map(tag => tag.toLowerCase()));
+        const column = options.column ?? DEFAULT_COLUMN;
+
+        /** Report and fix the spacing a single tag line carries. */
+        function inspect(line, start) {
+            const match = TAG_LINE.exec(line);
+
+            if (!match) {
+                return;
+            }
+
+            const [, prefix, tag, spacing] = match;
+
+            if (!tags.has(tag.toLowerCase())) {
+                return;
+            }
+
+            const desired = padding(tag, column);
+
+            if (desired === null || spacing === desired) {
+                return;
+            }
+
+            const from = start + prefix.length + 1 + tag.length;
+            const to = from + spacing.length;
+
+            context.report({
+                loc: {
+                    start: sourceCode.getLocFromIndex(from),
+                    end: sourceCode.getLocFromIndex(to),
+                },
+                messageId: 'misaligned',
+                data: { tag, column },
+                fix: fixer => fixer.replaceTextRange([from, to], desired),
+            });
+        }
+
+        return {
+            Program() {
+                for (const comment of sourceCode.getAllComments()) {
+                    if (comment.type !== 'Block' || !comment.value.startsWith('*')) {
+                        continue;
+                    }
+
+                    // The comment's value begins after the opening `/*`, so an
+                    // offset within it maps onto the source two characters in.
+                    let offset = comment.range[0] + 2;
+
+                    for (const line of comment.value.split('\n')) {
+                        inspect(line, offset);
+                        offset += line.length + 1;
+                    }
+                }
+            },
+        };
+    },
+});

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/pad-block-start.js

@@ -0,0 +1,85 @@
+import { createRule } from './lib.js';
+
+/** The member-carrying bodies whose first line is held clear of the brace. */
+const BODY_TYPES = new Set(['TSInterfaceBody', 'ClassBody', 'TSEnumBody']);
+
+/**
+ * Require a blank line after the opening brace of an interface, class or enum
+ * body.
+ *
+ * The first member then stands off from the declaration the way every later
+ * member stands off from the one above it, so a body reads as an evenly spaced
+ * list rather than crowding its opening line. Only the opening brace is
+ * governed; the closing brace is left to sit against the final member.
+ *
+ * An empty body and a body written entirely on one line carry no member to
+ * separate and are left alone. Where the first member opens with a
+ * documentation comment the blank line falls above the comment, so the comment
+ * stays attached to what it documents.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'pad-block-start',
+    meta: {
+        type: 'layout',
+        fixable: 'whitespace',
+        docs: {
+            description: 'Require a blank line after the opening brace of an interface, class or enum body.',
+        },
+        schema: [],
+        messages: {
+            missing: 'A body must begin with a blank line after its opening brace.',
+        },
+    },
+    defaultOptions: [],
+    create(context) {
+        const { sourceCode } = context;
+
+        /** Hold the first member of a body clear of the opening brace. */
+        function inspect(node) {
+            const brace = sourceCode.getFirstToken(node);
+            const close = sourceCode.getLastToken(node);
+
+            // A one-line body has no member to separate from the brace.
+            if (!brace || !close || brace.loc.end.line === close.loc.start.line) {
+                return;
+            }
+
+            const first = sourceCode.getTokenAfter(brace, { includeComments: true });
+
+            // An empty body carries nothing to stand off from the brace.
+            if (!first || first === close) {
+                return;
+            }
+
+            const blanks = first.loc.start.line - brace.loc.end.line - 1;
+
+            if (blanks === 1) {
+                return;
+            }
+
+            const onOwnLine = first.loc.start.line > brace.loc.end.line;
+
+            context.report({
+                loc: brace.loc,
+                messageId: 'missing',
+                fix: onOwnLine
+                    ? fixer => fixer.replaceTextRange(
+                        [brace.range[1], first.range[0]],
+                        `\n\n${' '.repeat(first.loc.start.column)}`,
+                    )
+                    : null,
+            });
+        }
+
+        const visitor = {};
+
+        for (const type of BODY_TYPES) {
+            visitor[type] = inspect;
+        }
+
+        return visitor;
+    },
+});

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.10.0",
+    "version": "1.12.0",
     "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>",