@sinemacula/coding-standards 1.14.0 → 1.16.0

package/README.md

@@ -274,7 +274,7 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 | `SineMacula.Attributes.DisallowToolingAttribute`           | No IDE/tooling attributes (e.g. `JetBrains\PhpStorm`).                      |
 | `SineMacula.Classes.RequireFinalClass`                     | Concrete classes must be `final` or `abstract` (`@inheritable` opts out).   |
 | `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.CommentLineLength`                  | Standalone comment prose wrapped to 80 chars; premature wraps also fixed.   |
 | `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.              |
@@ -321,6 +321,7 @@ type-checked layer.
 | `@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; premature wraps also fixed.           |
 
 `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
@@ -331,8 +332,17 @@ members (interface property signatures, enum members and data class fields) take
 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
+`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. Markdown
+headings, docblock tag lines, suppression directives, 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)
+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, 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

package/js/eslint/index.js

@@ -52,7 +52,9 @@ export default [
             '@sinemacula/align-doc-tags': 'error',
             '@sinemacula/single-line-property-doc': 'error',
             '@sinemacula/multiline-function-doc': 'error',
+            '@sinemacula/comment-line-wrap': 'error',
 
+            curly: ['error', 'all'],
             'max-lines-per-function': ['error', { max: 50, skipComments: true, skipBlankLines: true, IIFEs: true }],
             'max-depth': ['error', 4],
 

package/js/eslint/plugin.js

@@ -1,5 +1,6 @@
 import alignDocTags from './rules/align-doc-tags.js';
 import booleanMethodName from './rules/boolean-method-name.js';
+import commentLineWrap from './rules/comment-line-wrap.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';
@@ -36,5 +37,6 @@ export default {
         'align-doc-tags': alignDocTags,
         'single-line-property-doc': singleLinePropertyDoc,
         'multiline-function-doc': multilineFunctionDoc,
+        'comment-line-wrap': commentLineWrap,
     },
 };

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

@@ -278,13 +278,12 @@ function buildListeners(state) {
  * guard, ...) that returns a result bool is exempt via COMMAND_VERBS. A member
  * may also opt out with an
  * @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
- * through the rule options.
+ * 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 through the rule options.
  *
  * @author      Ben Carey <bdmc@sinemacula.co.uk>
  * @copyright   2026 Sine Macula Limited

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

@@ -0,0 +1,140 @@
+/**
+ * Classifies a single content line of a comment.
+ *
+ * Only prose and list items are reflowed; every other kind is preserved
+ * verbatim and acts as a paragraph boundary. Directives, docblock tags, fenced
+ * or indented code, tables and rule separators are left exactly as written, so
+ * a reflow never disturbs a construct whose position or spacing carries
+ * meaning.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+
+import { len, trimAscii } from './comment-tokenizer.js';
+
+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 HEADING = new RegExp(`^#{1,6}${WS}`);
+const DIRECTIVE = /^(phpcs:|phpstan-ignore|@phpstan-|@psalm-|@phan-|eslint-disable|eslint-enable|@ts-|prettier-ignore|stylelint-|@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}+`);
+
+/** The kinds a comment content line can take. Only prose and lists reflow. */
+export const KIND = {
+    BLANK: 'blank',
+    PROSE: 'prose',
+    LIST: 'list',
+    TAG: 'tag',
+    DIRECTIVE: 'directive',
+    SEPARATOR: 'separator',
+    TABLE: 'table',
+    FENCE: 'fence',
+    CODE: 'code',
+    HEADING: 'heading',
+};
+
+/** The ordered rules mapping the first matching leading mark to a kind. */
+const KINDS = [
+    { kind: KIND.FENCE, test: ({ trimmed }) => FENCE.test(trimmed) },
+    { 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, '')) },
+];
+
+/**
+ * Classify a content line, given whether it sits inside a fenced block.
+ */
+export function classify(content, inFence) {
+    const trimmed = trimAscii(content);
+
+    if (inFence) {
+        return KIND.FENCE;
+    }
+
+    return trimmed === '' ? KIND.BLANK : kindOf(content, trimmed);
+}
+
+/** Classify a non-blank line by its leading marks, defaulting to prose. */
+function kindOf(content, trimmed) {
+    const line = { content, trimmed };
+
+    return KINDS.find(({ test }) => test(line))?.kind ?? KIND.PROSE;
+}
+
+/** Whether a content line opens or closes a fenced block. */
+export function isFence(content) {
+    return FENCE.test(trimAscii(content));
+}
+
+/** Parse a list marker into its bullet, indent and occupied width, or null. */
+export function listMarker(content) {
+    const match = LIST_MARKER.exec(content);
+
+    if (!match) {
+        return null;
+    }
+
+    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-line-wrap.js

@@ -0,0 +1,198 @@
+import { createRule } from './lib.js';
+import { reflow } from './comment-reflow.js';
+
+const DEFAULT_MAX_LENGTH = 80;
+
+/** A docblock interior line: its indent, the star, and the prose after it. */
+const DOC_LINE = /^([ \t\n\r\f\v]*)\*( ?)(.*)$/;
+
+/** Whether only whitespace precedes the comment on its own line. */
+function isStandalone(comment, sourceCode) {
+    const line = sourceCode.lines[comment.loc.start.line - 1];
+
+    return line.slice(0, comment.loc.start.column).trim() === '';
+}
+
+/**
+ * Group standalone `//` comments into runs of adjacent lines sharing an indent,
+ * so a wrapped paragraph is reflowed as one unit.
+ */
+function slashRuns(comments, sourceCode) {
+    const runs = [];
+    let current = null;
+
+    for (const comment of comments) {
+        if (comment.type !== 'Line' || !isStandalone(comment, sourceCode)) {
+            current = null;
+            continue;
+        }
+
+        const last = current?.[current.length - 1];
+
+        if (current && comment.loc.start.line === last.loc.start.line + 1 && comment.loc.start.column === current[0].loc.start.column) {
+            current.push(comment);
+        } else {
+            current = [comment];
+            runs.push(current);
+        }
+    }
+
+    return runs;
+}
+
+/** Strip the single optional space that follows a `//` from a comment's value. */
+function slashContent(value) {
+    return value.startsWith(' ') ? value.slice(1) : value;
+}
+
+/** Describe a `//` run: its content lines, margin, report locations and rebuild. */
+function slashDescriptor(run, sourceCode, eol) {
+    const first = run[0].loc.start;
+    const indent = sourceCode.lines[first.line - 1].slice(0, first.column);
+
+    return {
+        content: run.map(comment => slashContent(comment.value)),
+        marginWidth: indent.length + 3,
+        locs: run.map(comment => comment.loc),
+        range: [run[0].range[0], run[run.length - 1].range[1]],
+        rebuild: lines => lines.map((line, offset) => `${offset === 0 ? '' : indent}//${line === '' ? '' : ` ${line}`}`).join(eol),
+    };
+}
+
+/** The margin-stripped interior lines of a docblock, or null for an odd shape. */
+function docContent(comment, sourceCode) {
+    const { lines } = sourceCode;
+    const open = comment.loc.start.line;
+    const close = comment.loc.end.line;
+
+    if (open === close || lines[open - 1].trim() !== '/**' || lines[close - 1].trim() !== '*/') {
+        return null;
+    }
+
+    const content = [];
+    const locs = [];
+    let indent = null;
+
+    for (let line = open + 1; line < close; line += 1) {
+        const match = DOC_LINE.exec(lines[line - 1]);
+
+        if (!match || (indent !== null && match[1] !== indent)) {
+            return null;
+        }
+
+        indent ??= match[1];
+        content.push(match[3]);
+        locs.push({ start: { line, column: 0 }, end: { line, column: lines[line - 1].length } });
+    }
+
+    return content.length === 0 ? null : { content, locs, indent };
+}
+
+/** Describe a docblock: its content lines, margin, report locations and rebuild. */
+function docDescriptor(comment, sourceCode, eol) {
+    if (comment.type !== 'Block' || !comment.value.startsWith('*')) {
+        return null;
+    }
+
+    const parsed = docContent(comment, sourceCode);
+
+    if (parsed === null) {
+        return null;
+    }
+
+    const { content, locs, indent } = parsed;
+
+    return {
+        content,
+        marginWidth: indent.length + 2,
+        locs,
+        range: comment.range,
+        rebuild: lines => `/**${eol}${lines.map(line => (line === '' ? `${indent}*` : `${indent}* ${line}`)).join(eol)}${eol}${indent}*/`,
+    };
+}
+
+/** Reflow a block and report each overflowing and prematurely wrapped line. */
+function enforce(context, descriptor, maxLength) {
+    const result = reflow(descriptor.content, descriptor.marginWidth, maxLength);
+
+    if (result.long.length === 0 && result.premature.length === 0) {
+        return;
+    }
+
+    /** Replace the whole comment block with its reflowed, canonical form. */
+    const fix = fixer => fixer.replaceTextRange(descriptor.range, descriptor.rebuild(result.lines));
+
+    /** Report one faulted line under the given message. */
+    const report = (index, messageId) => context.report({ loc: descriptor.locs[index], messageId, data: { max: maxLength }, fix });
+
+    result.long.forEach(index => report(index, 'tooLong'));
+    result.premature.forEach(index => report(index, 'prematureWrap'));
+}
+
+/**
+ * Keep standalone comment prose wrapped to a readable width.
+ *
+ * The syntax-only counterpart of the PHP comment line length sniff. It fills
+ * each line greedily with as many whole words as fit and reports two faults on
+ * their own footings: a line that overflows the width, and a line that wraps
+ * earlier than it needs to. Standalone `//` runs and multi-line docblocks are
+ * governed; tag lines, suppression directives, fenced or indented code, tables,
+ * separators and trailing comments after code are left untouched, as is a line
+ * whose overflow is a single unbreakable token such as a long name or URL, and
+ * a compact single-line docblock, which the single-line property rule governs.
+ * The fix reflows each faulted paragraph to its greedy canonical form and is
+ * idempotent.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+export default createRule({
+    name: 'comment-line-wrap',
+    meta: {
+        type: 'layout',
+        fixable: 'whitespace',
+        docs: {
+            description: 'Keep standalone comment prose wrapped greedily to a readable width.',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    maxLength: {
+                        type: 'integer',
+                        minimum: 1,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            tooLong: 'Comment line must not exceed {{ max }} characters.',
+            prematureWrap: 'Comment line wraps before it needs to; the next word fits within {{ max }} characters.',
+        },
+    },
+    defaultOptions: [{ maxLength: DEFAULT_MAX_LENGTH }],
+    create(context, [options]) {
+        const { sourceCode } = context;
+        const maxLength = options.maxLength ?? DEFAULT_MAX_LENGTH;
+        const eol = sourceCode.text.includes('\r\n') ? '\r\n' : '\n';
+
+        return {
+            Program() {
+                const comments = sourceCode.getAllComments();
+
+                for (const run of slashRuns(comments, sourceCode)) {
+                    enforce(context, slashDescriptor(run, sourceCode, eol), maxLength);
+                }
+
+                for (const comment of comments) {
+                    const descriptor = docDescriptor(comment, sourceCode, eol);
+
+                    if (descriptor !== null) {
+                        enforce(context, descriptor, maxLength);
+                    }
+                }
+            },
+        };
+    },
+});

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

@@ -0,0 +1,159 @@
+/**
+ * Reflows a single paragraph of comment prose to its greedy canonical form.
+ *
+ * A paragraph is a run of prose lines, or one list item with its continuation
+ * lines. It is filled line by line with as many whole words as the width
+ * allows, never splitting a word and keeping any list marker's hanging indent.
+ * A paragraph is reflowed only when it is safe to: it holds no token wider than
+ * the line, is not too narrow, and would still read as prose once wrapped.
+ * Otherwise it is returned untouched.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+
+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+[.)]|#{1,6})$/;
+
+/**
+ * Reflow a paragraph, returning its output lines and the faults found, their
+ * indices offset from the given base, or the verbatim input when it cannot be
+ * reflowed or carries no fault.
+ */
+export function reflowParagraph(slice, marker, marginWidth, maxLength, base) {
+    const wrapped = wrapLines(slice, marker, marginWidth, maxLength);
+    const faults = wrapped === null ? { long: [], premature: [] } : findFaults(slice, marginWidth, maxLength);
+
+    if (wrapped === null || (faults.long.length === 0 && faults.premature.length === 0)) {
+        return { lines: slice, long: [], premature: [] };
+    }
+
+    return {
+        lines: wrapped,
+        long: faults.long.map(offset => base + offset),
+        premature: faults.premature.map(offset => base + offset),
+    };
+}
+
+/**
+ * The greedy canonical lines of a paragraph, or null when it holds an
+ * unwrappable token, is too narrow, or would re-classify once wrapped.
+ */
+function wrapLines(slice, marker, marginWidth, maxLength) {
+    const indent = marker === null ? leadingSpaces(slice[0]) : marker.indent;
+    const hanging = indent + (marker === null ? 0 : marker.width);
+    const width = maxLength - marginWidth - hanging;
+    const tokens = glue(tokenize(joinText(slice, marker)));
+
+    if (width < 1 || tokens.length === 0 || longestToken(tokens) > width) {
+        return null;
+    }
+
+    const lines = layout(greedy(tokens, width), marker, indent, hanging);
+
+    return stable(lines, marker) ? lines : null;
+}
+
+/** Assemble output lines, prefixing the marker then the hanging indent. */
+function layout(wrapped, marker, indent, hanging) {
+    return wrapped.map((text, offset) =>
+        offset === 0 && marker !== null
+            ? `${' '.repeat(indent)}${marker.marker} ${text}`
+            : `${' '.repeat(hanging)}${text}`,
+    );
+}
+
+/** Whether every reflowed line still classifies as it must. */
+function stable(lines, marker) {
+    return lines.every((line, offset) => {
+        const expected = offset === 0 && marker !== null ? KIND.LIST : KIND.PROSE;
+
+        return classify(line, false) === expected;
+    });
+}
+
+/** The input offsets that overflow the width and those that wrap early. */
+function findFaults(slice, marginWidth, maxLength) {
+    const long = [];
+    const premature = [];
+
+    slice.forEach((content, offset) => {
+        if (marginWidth + len(content) > maxLength) {
+            long.push(offset);
+        }
+        if (wrapsEarly(slice, offset, marginWidth, maxLength)) {
+            premature.push(offset);
+        }
+    });
+
+    return { long, premature };
+}
+
+/** Whether a line could hold the first word of the next line within the width. */
+function wrapsEarly(slice, offset, marginWidth, maxLength) {
+    if (offset + 1 >= slice.length) {
+        return false;
+    }
+
+    const next = glue(tokenize(slice[offset + 1]))[0] ?? '';
+
+    return next !== '' && marginWidth + len(slice[offset]) + 1 + len(next) <= maxLength;
+}
+
+/** Join a paragraph's lines, stripping any list marker from the first line. */
+function joinText(slice, marker) {
+    const first = marker === null ? trimAsciiStart(slice[0]) : slice[0].replace(LIST_MARKER, '');
+    const rest = slice.slice(1).map(line => trimAsciiStart(line));
+
+    return [first, ...rest].join(' ');
+}
+
+/** Merge backward any token that must never open a wrapped line. */
+function glue(tokens) {
+    const out = [];
+
+    for (const token of tokens) {
+        if (out.length > 0 && POISON.test(token)) {
+            out[out.length - 1] += ` ${token}`;
+        } else {
+            out.push(token);
+        }
+    }
+
+    return out;
+}
+
+/** Fill lines greedily with whole tokens up to the width. */
+function greedy(tokens, width) {
+    const lines = [];
+    let current = '';
+
+    for (const token of tokens) {
+        if (current === '') {
+            current = token;
+        } else if (len(current) + 1 + len(token) <= width) {
+            current += ` ${token}`;
+        } else {
+            lines.push(current);
+            current = token;
+        }
+    }
+
+    if (current !== '') {
+        lines.push(current);
+    }
+
+    return lines;
+}
+
+/** The length of the longest token. */
+function longestToken(tokens) {
+    return Math.max(...tokens.map(len));
+}
+
+/** The number of leading spaces on a line. */
+function leadingSpaces(text) {
+    return len(text) - len(trimAsciiStart(text));
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Deterministic greedy re-wrapper for comment prose.
+ *
+ * The syntax-only counterpart of the PHP comment line length sniff: given the
+ * 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. 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
+ * non-unicode PCRE `\s`).
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+
+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';
+export { tokenize } from './comment-tokenizer.js';
+
+/**
+ * Reflow a block's content lines to the greedy canonical form, returning the
+ * canonical lines and the indices of the input lines that overflow or wrap
+ * prematurely.
+ */
+export function reflow(lines, marginWidth, maxLength) {
+    const ctx = { out: [], long: [], premature: [], marginWidth, maxLength, inFence: false, typeDepth: 0 };
+    let i = 0;
+
+    while (i < lines.length) {
+        i = step(lines, i, ctx);
+    }
+
+    return { lines: ctx.out, long: ctx.long, premature: ctx.premature };
+}
+
+/**
+ * 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);
+    }
+    if (type === KIND.FENCE) {
+        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;
+}
+
+/**
+ * Append a run of prose or a list item, reflowed where it faults. A list line
+ * always parses to a marker, so it never reaches the plain-prose branch.
+ */
+function paragraph(lines, start, marker, ctx) {
+    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);
+
+    ctx.out.push(...segment.lines);
+    segment.long.forEach(offset => ctx.long.push(offset));
+    segment.premature.forEach(offset => ctx.premature.push(offset));
+
+    return end;
+}
+
+/**
+ * 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 && indentWidth(lines[end]) <= hanging) {
+        end += 1;
+    }
+
+    return end;
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Text primitives for the comment reflow engine.
+ *
+ * Splits prose into wrapping tokens, keeping inline code, an inline `{@link}`
+ * tag and a Markdown link whole even when they hold spaces, and measures widths
+ * in Unicode code points. Widths and whitespace match the PHP engine exactly:
+ * code points as mb_strlen counts them, and ASCII-only trimming as trim does.
+ *
+ * @author      Ben Carey <bdmc@sinemacula.co.uk>
+ * @copyright   2026 Sine Macula Limited
+ */
+
+const ASCII_TRIM = /^[ \t\n\r\0\v]+|[ \t\n\r\0\v]+$/g;
+const ASCII_TRIM_START = /^[ \t\n\r\0\v]+/;
+
+/** The number of Unicode code points in a string, matching PHP mb_strlen. */
+export function len(text) {
+    return [...text].length;
+}
+
+/** Strip leading and trailing ASCII whitespace, matching PHP trim. */
+export function trimAscii(text) {
+    return text.replace(ASCII_TRIM, '');
+}
+
+/** Strip leading ASCII whitespace, matching PHP ltrim. */
+export function trimAsciiStart(text) {
+    return text.replace(ASCII_TRIM_START, '');
+}
+
+/**
+ * Split a line of prose into tokens, keeping inline code, link tags and
+ * Markdown links whole even when they hold spaces.
+ */
+export function tokenize(text) {
+    const chars = [...text];
+    const tokens = [];
+    let i = 0;
+
+    while (i < chars.length) {
+        if (chars[i] === ' ') {
+            i += 1;
+            continue;
+        }
+
+        const start = i;
+        i = consumeToken(chars, i);
+        tokens.push(chars.slice(start, i).join(''));
+    }
+
+    return tokens;
+}
+
+/** Advance past one token, stepping over any atomic span it contains. */
+function consumeToken(chars, i) {
+    while (i < chars.length && chars[i] !== ' ') {
+        if (chars[i] === '`') {
+            i = consumeSpan(chars, i, '`');
+        } else if (chars[i] === '{' && chars[i + 1] === '@') {
+            i = consumeSpan(chars, i, '}');
+        } else if (chars[i] === '[') {
+            i = consumeLink(chars, i);
+        } else {
+            i += 1;
+        }
+    }
+
+    return i;
+}
+
+/** Advance past a delimited span to its closer, or by one when it never closes. */
+function consumeSpan(chars, i, close) {
+    const found = chars.indexOf(close, i + 1);
+
+    return found === -1 ? i + 1 : found + 1;
+}
+
+/** Advance past a Markdown link, or by one when the shape does not hold. */
+function consumeLink(chars, i) {
+    const label = consumeSpan(chars, i, ']');
+
+    if (label === i + 1 || chars[label] !== '(') {
+        return i + 1;
+    }
+
+    const target = consumeSpan(chars, label, ')');
+
+    return target === label + 1 ? i + 1 : target;
+}

package/js/eslint/vue.js

@@ -8,14 +8,14 @@ import tseslint from 'typescript-eslint';
  * through the TypeScript parser, and holds component filenames to the same
  * kebab-case convention the shared formatter enforces on plain sources.
  *
- * This layer also carries the template layout rules, which the shared
- * formatter cannot: it does not understand single-file components, so `.vue`
- * markup would otherwise go unformatted entirely.
+ * This layer also carries the template layout rules, which the shared formatter
+ * cannot: it does not understand single-file components, so `.vue` markup would
+ * otherwise go unformatted entirely.
  *
  * Additive, and deliberately unlike the type-aware layer: it carries no base
  * rules of its own, so spread it after whichever layer a repo already uses
- * rather than in place of one. Vue is orthogonal to type-awareness, and a
- * repo enabling both would otherwise apply the base rules twice.
+ * rather than in place of one. Vue is orthogonal to type-awareness, and a repo
+ * enabling both would otherwise apply the base rules twice.
  *
  * @author      Ben Carey <bdmc@sinemacula.co.uk>
  * @copyright   2026 Sine Macula Limited

package/package.json

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