@sinemacula/coding-standards 1.22.0 → 1.23.0

package/README.md

@@ -417,19 +417,30 @@ type-checked layer. Every rule is scoped to `.ts`/`.js`; `comment-line-wrap` alo
 | `@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/require-file-description`         | The same comment must open with a prose summary above those tags.                   |
 | `@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.                 |
 | `@sinemacula/comment-line-wrap`                | Standalone comment prose wrapped to 80 chars, YAML included; premature wraps too.   |
 
-`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.
+`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` and `require-file-description` each take `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.
+
+`require-copyright` and `require-file-description` divide the file header between them: the first asks that a single
+block comment carry `@copyright` and `@author`, the second that the same block open with a prose summary above them,
+which is the shape the convention has always described and the half nothing enforced. Both find that block by the
+tags it carries rather than by its position, so a module documented at its export below the imports is read as the
+header exactly as a comment at the top of the file is; a project that narrows one rule's `tags` should narrow the
+other's to match. Only the block's first non-blank line is read, and only for whether it is prose rather than a tag,
+which puts the summary above the tags and stops a wrapped tag value's continuation line passing as one. What the
+summary says is the author's business. A file carrying no such block at all is left to `require-copyright`, so one
+missing header is never faulted twice.
 
 `comment-line-wrap` takes `maxLength` (default 80) and is the syntax-only counterpart of the PHP
 `SineMacula.Commenting.CommentLineLength` sniff. It fills standalone `//` and `#` runs and multi-line docblock prose
@@ -450,10 +461,18 @@ than comment, so a shell comment inside a `run: |` step is never seen, and a com
 
 The base layer also switches on a set of built-in rules: `@typescript-eslint/no-explicit-any`, `curly` (a brace on every
 control statement, as PSR-12 already requires on the PHP side), `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, class, interface member and class field, require a description on every `@param` and `@returns`, 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`.
+and `max-depth` (4, test code exempt), plus `eslint-plugin-jsdoc` rules that require a documentation comment on every
+declared function, method, class, interface member and class field, require a description on every `@param` and
+`@returns`, 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`.
+
+Test files - `*.test.*`, `*.spec.*` and anything under `__tests__/`, `tests/` or `test-support/` - are exempt from
+`max-lines-per-function` and `max-depth` alone. A spec body is a long, deeply nested account of one scenario, and
+splitting it to satisfy a metric hides the scenario rather than simplifying it. They are not exempt from documentation:
+`jsdoc/require-jsdoc` reaches declared functions, assigned arrows and classes, which in a spec file are its helpers,
+factories and builders - the code a reader has to understand before the assertions mean anything. A test case is an
+arrow passed as a call argument, which none of the rule's contexts match, so `it('...', () => {})` is never asked to
+carry a block; a spec of test cases alone carries no documentation burden at all.
 
 `jsdoc/no-types`, which forbids a type in `@param`/`@returns`, runs over `.ts`/`.tsx`/`.mts`/`.cts` alone, alongside
 `@typescript-eslint/no-explicit-any`. A TypeScript signature already records the type, so the tag would only repeat it

package/js/eslint/index.js

@@ -63,6 +63,7 @@ export default [
             '@sinemacula/max-methods-per-class': 'error',
             '@sinemacula/no-base-error': 'error',
             '@sinemacula/require-copyright': 'error',
+            '@sinemacula/require-file-description': 'error',
             '@sinemacula/align-doc-tags': 'error',
             '@sinemacula/single-line-property-doc': 'error',
             '@sinemacula/multiline-function-doc': 'error',
@@ -125,11 +126,19 @@ export default [
         },
     },
     {
+        // Test code keeps the length and depth exemptions and nothing else. A
+        // spec body is a long, deeply nested account of one scenario, and
+        // splitting it to satisfy a metric hides the scenario rather than
+        // simplifying it. Documentation is a different matter: require-jsdoc's
+        // contexts reach declared functions, assigned arrows and classes, which
+        // in a spec file are its helpers, factories and builders - the code a
+        // reader has to understand before the assertions mean anything. A test
+        // case itself is an arrow passed as a call argument, which no context
+        // reaches, so `it('...', () => {})` is never asked to carry a block.
         files: ['**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}', '**/__tests__/**', '**/tests/**', '**/test-support/**'],
         rules: {
             'max-lines-per-function': 'off',
             'max-depth': 'off',
-            'jsdoc/require-jsdoc': 'off',
         },
     },
 ];

package/js/eslint/plugin.js

@@ -7,6 +7,7 @@ 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 requireFileDescription from './rules/require-file-description.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';
@@ -34,6 +35,7 @@ export default {
         'max-methods-per-class': maxMethodsPerClass,
         'no-base-error': noBaseError,
         'require-copyright': requireCopyright,
+        'require-file-description': requireFileDescription,
         'align-doc-tags': alignDocTags,
         'single-line-property-doc': singleLinePropertyDoc,
         'multiline-function-doc': multilineFunctionDoc,

package/js/eslint/rules/lib.js

@@ -92,3 +92,27 @@ export function isTestClass(klass) {
 
     return parent !== null && parent.endsWith('TestCase');
 }
+
+/** A boundary-anchored matcher for a documentation tag by its bare name. */
+export function tagMatcher(tag) {
+    const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+    return new RegExp(`(?:^|[\\s*])@${escaped}(?![-\\w])`, 'i');
+}
+
+/**
+ * The file's descriptive docblock: the block comment carrying all of the given
+ * tags together, or null when no comment carries them.
+ *
+ * The block is found by its tags rather than its position, since the header
+ * need not open the file: a module documented at its export sits below the
+ * imports. Requiring one comment to carry every tag is what makes the match a
+ * single block rather than a header split across several.
+ */
+export function fileDocBlock(sourceCode, tags) {
+    const matchers = tags.map(tagMatcher);
+
+    return sourceCode.getAllComments().find(
+        comment => comment.type === 'Block' && matchers.every(matcher => matcher.test(comment.value)),
+    ) ?? null;
+}

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

@@ -1,14 +1,7 @@
-import { createRule } from './lib.js';
+import { createRule, fileDocBlock } 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.
@@ -17,7 +10,9 @@ function tagMatcher(tag) {
  * 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.
+ * configurable, so a project may drop `@author` or add tags of its own. The
+ * summary those tags sit beside is the separate concern of
+ * `require-file-description`, which locates the same block by the same tags.
  *
  * @author      Ben Carey <bdmc@sinemacula.co.uk>
  * @copyright   2026 Sine Macula Limited
@@ -49,15 +44,10 @@ export default createRule({
     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) {
+                if (fileDocBlock(sourceCode, required) !== null) {
                     return;
                 }
 

package/js/eslint/rules/require-file-description.js

@@ -0,0 +1,97 @@
+import { createRule, fileDocBlock } from './lib.js';
+
+const DEFAULT_TAGS = ['copyright', 'author'];
+
+/** A line opening a documentation tag rather than carrying prose. */
+const TAG_LINE = /^@[A-Za-z][\w-]*(?:\s|$)/;
+
+/** The prose a documentation line carries, with its leading margin removed. */
+function content(line) {
+    return line.replace(/^\s*\*\s*/, '').trim();
+}
+
+/** Whether the block opens with prose rather than going straight to its tags. */
+function described(comment) {
+    for (const line of comment.value.split('\n')) {
+        const text = content(line);
+
+        if (text === '') {
+            continue;
+        }
+
+        return !TAG_LINE.test(text);
+    }
+
+    return false;
+}
+
+/**
+ * Require the file's descriptive docblock to carry a summary, not tags alone.
+ *
+ * The house convention is a prose summary followed by the tags every file
+ * declares, so `@author` and `@copyright` annotate a description rather than
+ * standing as a header of their own. `require-copyright` has always asked for
+ * the tags; this asks for the sentence they were meant to sit beneath, which
+ * was the intent all along and the half nothing enforced. A file whose entire
+ * header is two tags says who owns it and nothing about what it is.
+ *
+ * The block is located exactly as `require-copyright` locates it, by the tags
+ * it carries, so the two rules always speak about the same comment; a project
+ * changing one rule's `tags` should change the other's to match. A file with no
+ * such block is left alone, since `require-copyright` already owns the block's
+ * existence and faulting one omission twice would only double the report.
+ *
+ * Only the block's first non-blank line is read, and only whether it is prose.
+ * That places the summary above the tags, as the convention writes it, and
+ * keeps a wrapped tag value's continuation line from passing as a description.
+ * What the sentence says is the author's business: the rule asserts that prose
+ * is there, never that it is good.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'require-file-description',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: "Require the file's documentation comment to open with a description.",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missing: 'The documentation comment carrying {{ tags }} must open with a description.',
+        },
+    },
+    defaultOptions: [{ tags: DEFAULT_TAGS }],
+    create(context, [options]) {
+        const { sourceCode } = context;
+        const required = options.tags ?? DEFAULT_TAGS;
+
+        return {
+            Program() {
+                const doc = fileDocBlock(sourceCode, required);
+
+                if (doc === null || described(doc)) {
+                    return;
+                }
+
+                context.report({
+                    node: doc,
+                    messageId: 'missing',
+                    data: { tags: required.map(tag => `@${tag}`).join(', ') },
+                });
+            },
+        };
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sinemacula/coding-standards",
-    "version": "1.22.0",
+    "version": "1.23.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>",
@@ -58,7 +58,7 @@
         "eslint-plugin-vue": "^10.0.0",
         "typescript": "^5.0.0",
         "typescript-eslint": "^8.0.0",
-        "vitest": "^3.0.0",
+        "vitest": "^4.1.11",
         "vue-eslint-parser": "^10.0.0",
         "yaml-eslint-parser": "^2.1.0"
     },