@sinemacula/coding-standards 1.15.0 → 1.17.0

package/README.md

@@ -334,10 +334,12 @@ one line where present; a free function keeps the freedom of either shape.
 
 `comment-line-wrap` takes `maxLength` (default 80) and is the syntax-only counterpart of the PHP
 `SineMacula.Commenting.CommentLineLength` sniff. It fills standalone `//` runs and multi-line docblock prose greedily,
-reporting an overflowing line and a prematurely wrapped line on their own footings and autofixing both. Docblock tag
-lines, suppression directives, fenced or indented code, tables, separators, a line whose overflow is a single
-unbreakable token such as a long name or URL, trailing comments after code and compact single-line docblocks are left
-untouched.
+reporting an overflowing line and a prematurely wrapped line on their own footings and autofixing both. Markdown
+headings, docblock tag lines, machine-parsed tool directives (`eslint`, `biome-ignore`, `@ts-`, `Stryker`, `c8`/`v8`/
+`istanbul ignore`, `@vite-ignore` and the like), fenced code, an indented code or command block, a doc-tag whose
+value opens a multi-line bracketed type (an `array{...}` shape, a `<...>` generic or a `\Closure(...)` signature),
+tables, separators, a line whose overflow is a single unbreakable token such as a long name or URL, trailing comments
+after code and compact single-line docblocks are left untouched.
 
 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)

package/js/eslint/rules/comment-classifier.js

@@ -17,10 +17,19 @@ const WS = '[ \\t\\n\\r\\f\\v]';
 const FENCE = /^(```|~~~)/;
 const TAG = new RegExp(`^@[A-Za-z][A-Za-z0-9-]*(?=${WS}|$)`);
 const LIST = new RegExp(`^${WS}*([-*+]|\\d+[.)])${WS}+`);
-const DIRECTIVE = /^(phpcs:|phpstan-ignore|@phpstan-|@psalm-|@phan-|eslint-disable|eslint-enable|@ts-|prettier-ignore|stylelint-|@codingStandards|@SuppressWarnings|NOSONAR|qlty-ignore)/;
+const HEADING = new RegExp(`^#{1,6}${WS}`);
+const DIRECTIVE = /^(phpcs:|phpstan-ignore|@phpstan-|@psalm-|@phan-|eslint\b|globals?\b|exported\b|biome-ignore\b|@ts-|prettier-ignore|stylelint-|Stryker (?:disable|restore)\b|(?:c8|v8|istanbul) ignore\b|@vite-ignore\b|webpackChunkName\b|@preserve\b|@license\b|@codingStandards|@SuppressWarnings|NOSONAR|qlty-ignore)/;
 const SEPARATOR = /^[=\-~*_#.+ ]{3,}$/;
 const CODE = new RegExp(`=>|->|::|;${WS}*$|\\{${WS}*$|^\\}|^(?:if|elseif|for|foreach|while|switch|catch)${WS}*\\(|^[\\w$>[\\]'.-]+${WS}*=[^=>]|^\\$`);
 const SPAN = /`[^`]*`|\{@[^}]*\}|\[[^\]]*\]\([^)]*\)/g;
+const TYPE_TAG = /^@(?:(?:phpstan|psalm|phan)-(?:type|import-type|param|return|var)|var|param|return|typedef|type|property|returns)\b/;
+const TYPE_CONTINUES = /[{<(,:|&]\s*$/;
+const QUOTE = /'[^']*'|"[^"]*"/g;
+const INDENT = /^(?: {2,}|\t)/;
+const LEADING_SPACES = /^ +/;
+const ARROWS = /->|=>/g;
+const OPENERS = /[{<(]/g;
+const CLOSERS = /[}>)]/g;
 
 /** A list marker: a bullet or an ordered number, and the space after it. */
 export const LIST_MARKER = new RegExp(`^(${WS}*)([-*+]|\\d+[.)])${WS}+`);
@@ -36,6 +45,7 @@ export const KIND = {
     TABLE: 'table',
     FENCE: 'fence',
     CODE: 'code',
+    HEADING: 'heading',
 };
 
 /** The ordered rules mapping the first matching leading mark to a kind. */
@@ -44,6 +54,7 @@ const KINDS = [
     { kind: KIND.DIRECTIVE, test: ({ trimmed }) => DIRECTIVE.test(trimmed) },
     { kind: KIND.TAG, test: ({ trimmed }) => TAG.test(trimmed) },
     { kind: KIND.TABLE, test: ({ trimmed }) => trimmed.startsWith('|') },
+    { kind: KIND.HEADING, test: ({ trimmed }) => HEADING.test(trimmed) },
     { kind: KIND.SEPARATOR, test: ({ trimmed }) => SEPARATOR.test(trimmed) },
     { kind: KIND.LIST, test: ({ content }) => LIST.test(content) },
     { kind: KIND.CODE, test: ({ trimmed }) => CODE.test(trimmed.replace(SPAN, '')) },
@@ -84,3 +95,46 @@ export function listMarker(content) {
 
     return { marker: match[2], indent: len(match[1]), width: len(match[2]) + 1 };
 }
+
+/** Whether a content line is indented past the baseline: a tab or two spaces. */
+export function indented(content) {
+    return INDENT.test(content);
+}
+
+/** The number of leading spaces on a content line, for the hanging-indent bound. */
+export function indentWidth(content) {
+    return content.length - content.replace(LEADING_SPACES, '').length;
+}
+
+/** Whether a line ends the verbatim type block before it: a blank line or a fresh tag. */
+export function isTypeBoundary(content) {
+    const trimmed = trimAscii(content);
+
+    return trimmed === '' || trimmed.startsWith('@');
+}
+
+/** The net depth a line's type slot opens, ignoring inline spans and arrows. */
+export function bracketDelta(text) {
+    const stripped = typeSlot(text).replace(ARROWS, '');
+
+    return (stripped.match(OPENERS) ?? []).length - (stripped.match(CLOSERS) ?? []).length;
+}
+
+/** The depth a type-annotation tag opens, or zero when it is not one or closes here. */
+export function typeTagDepth(content) {
+    if (!TYPE_TAG.test(trimAscii(content))) {
+        return 0;
+    }
+
+    const delta = bracketDelta(content);
+
+    return delta > 0 && TYPE_CONTINUES.test(typeSlot(content)) ? delta : 0;
+}
+
+/** The type-carrying portion of a line: spans and quotes removed, and everything from the first variable dropped. */
+function typeSlot(content) {
+    const stripped = content.replace(SPAN, '').replace(QUOTE, '');
+    const variable = stripped.indexOf('$');
+
+    return variable === -1 ? stripped : stripped.slice(0, variable);
+}

package/js/eslint/rules/comment-paragraph.js

@@ -15,7 +15,7 @@
 import { KIND, LIST_MARKER, classify } from './comment-classifier.js';
 import { len, tokenize, trimAsciiStart } from './comment-tokenizer.js';
 
-const POISON = /^(@[A-Za-z][A-Za-z0-9-]*|[-*+]|\d+[.)])$/;
+const POISON = /^(@[A-Za-z][A-Za-z0-9-]*|[-*+]|\d+[.)]|#{1,6})$/;
 
 /**
  * Reflow a paragraph, returning its output lines and the faults found, their

package/js/eslint/rules/comment-reflow.js

@@ -5,9 +5,10 @@
  * content lines of one comment block (their margin already stripped) and the
  * width that margin will reclaim, it walks the block and hands each run of
  * prose and each list item to a paragraph reflow, gathering the canonical lines
- * and the indices of the input lines that overflow or wrap prematurely. Tags,
- * directives, fenced or indented code, tables and separators are left verbatim
- * and bound the paragraph around them.
+ * and the indices of the input lines that overflow or wrap prematurely. A
+ * fenced block, a type-annotation tag whose value opens a bracketed type across
+ * lines, headings, indented code, tags, directives, tables and separators are
+ * left verbatim and bound the paragraph around them.
  *
  * Widths count Unicode code points and whitespace is matched as ASCII only, so
  * the output is byte-for-byte identical to the PHP engine (mb_strlen and the
@@ -17,7 +18,7 @@
  * @copyright   2026 Sine Macula Limited
  */
 
-import { KIND, classify, isFence, listMarker } from './comment-classifier.js';
+import { KIND, bracketDelta, classify, indentWidth, indented, isFence, isTypeBoundary, listMarker, typeTagDepth } from './comment-classifier.js';
 import { reflowParagraph } from './comment-paragraph.js';
 
 export { KIND, classify, isFence, listMarker } from './comment-classifier.js';
@@ -29,42 +30,73 @@ export { tokenize } from './comment-tokenizer.js';
  * prematurely.
  */
 export function reflow(lines, marginWidth, maxLength) {
-    const out = [];
-    const long = [];
-    const premature = [];
-    let inFence = false;
+    const ctx = { out: [], long: [], premature: [], marginWidth, maxLength, inFence: false, typeDepth: 0 };
     let i = 0;
 
     while (i < lines.length) {
-        const type = inFence ? KIND.FENCE : classify(lines[i], false);
-
-        if (inFence) {
-            out.push(lines[i]);
-            inFence = !isFence(lines[i]);
-            i += 1;
-        } else {
-            i = consume(lines, i, type, { out, long, premature, marginWidth, maxLength, fence: value => { inFence = value; } });
-        }
+        i = step(lines, i, ctx);
     }
 
-    return { lines: out, long, premature };
+    return { lines: ctx.out, long: ctx.long, premature: ctx.premature };
 }
 
-/** Handle one line or paragraph, appending its output and any faults. */
-function consume(lines, i, type, ctx) {
+/**
+ * Advance one line, keeping verbatim any line inside a fenced block or inside a
+ * type-annotation tag whose bracketed value is still open.
+ */
+function step(lines, i, ctx) {
+    const line = lines[i];
+
+    if (ctx.inFence) {
+        ctx.inFence = !isFence(line);
+
+        return verbatim(line, i, ctx);
+    }
+
+    if (ctx.typeDepth > 0 && !isTypeBoundary(line)) {
+        ctx.typeDepth = Math.max(0, ctx.typeDepth + bracketDelta(line));
+
+        return verbatim(line, i, ctx);
+    }
+
+    ctx.typeDepth = 0;
+
+    const opening = typeTagDepth(line);
+
+    if (opening > 0) {
+        ctx.typeDepth = opening;
+
+        return verbatim(line, i, ctx);
+    }
+
+    return consume(lines, i, ctx);
+}
+
+/** Dispatch a line by kind: an indented line is verbatim; else fence, prose or list. */
+function consume(lines, i, ctx) {
+    if (indented(lines[i])) {
+        return verbatim(lines[i], i, ctx);
+    }
+
+    const type = classify(lines[i], false);
+
     if (type === KIND.PROSE) {
         return paragraph(lines, i, null, ctx);
     }
     if (type === KIND.LIST) {
         return paragraph(lines, i, listMarker(lines[i]), ctx);
     }
-
-    ctx.out.push(lines[i]);
-
     if (type === KIND.FENCE) {
-        ctx.fence(true);
+        ctx.inFence = true;
     }
 
+    return verbatim(lines[i], i, ctx);
+}
+
+/** Emit one line unchanged and advance past it. */
+function verbatim(line, i, ctx) {
+    ctx.out.push(line);
+
     return i + 1;
 }
 
@@ -73,7 +105,7 @@ function consume(lines, i, type, ctx) {
  * always parses to a marker, so it never reaches the plain-prose branch.
  */
 function paragraph(lines, start, marker, ctx) {
-    const end = proseEnd(lines, marker === null ? start : start + 1);
+    const end = marker === null ? flushEnd(lines, start) : continuationEnd(lines, start + 1, marker.indent + marker.width);
     const slice = lines.slice(start, end);
     const segment = reflowParagraph(slice, marker, ctx.marginWidth, ctx.maxLength, start);
 
@@ -84,11 +116,28 @@ function paragraph(lines, start, marker, ctx) {
     return end;
 }
 
-/** The index one past the last prose line from the given start. */
-function proseEnd(lines, from) {
+/**
+ * The index one past the last flush prose line from the given start. An
+ * indented line ends the paragraph, bounding a verbatim indented code block.
+ */
+function flushEnd(lines, from) {
+    let end = from;
+
+    while (end < lines.length && classify(lines[end], false) === KIND.PROSE && !indented(lines[end])) {
+        end += 1;
+    }
+
+    return end;
+}
+
+/**
+ * The index one past the last continuation line of a list item. A line indented
+ * past the hanging indent is verbatim code, not a continuation.
+ */
+function continuationEnd(lines, from, hanging) {
     let end = from;
 
-    while (end < lines.length && classify(lines[end], false) === KIND.PROSE) {
+    while (end < lines.length && classify(lines[end], false) === KIND.PROSE && indentWidth(lines[end]) <= hanging) {
         end += 1;
     }
 

package/package.json

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