@sinemacula/coding-standards 1.10.0 → 1.11.0

package/README.md

@@ -282,14 +282,17 @@ 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. |
 
 `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.
 
 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).
+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
 `@typescript-eslint/only-throw-error`.
 

package/js/eslint/index.js

@@ -49,13 +49,17 @@ export default [
             '@sinemacula/max-methods-per-class': 'error',
             '@sinemacula/no-base-error': 'error',
             '@sinemacula/require-copyright': 'error',
+            '@sinemacula/align-doc-tags': '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).
+            // 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.
             'jsdoc/require-jsdoc': ['error', {
                 require: {
                     ClassDeclaration: true,
@@ -73,6 +77,7 @@ export default [
             '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,3 +1,4 @@
+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 noBaseError from './rules/no-base-error.js';
@@ -30,5 +31,6 @@ export default {
         'max-methods-per-class': maxMethodsPerClass,
         'no-base-error': noBaseError,
         'require-copyright': requireCopyright,
+        'align-doc-tags': alignDocTags,
     },
 };

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/package.json

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