@sinemacula/coding-standards 1.20.2 → 1.21.0

package/README.md

@@ -130,13 +130,17 @@ type-aware rules (the curated typescript-eslint set plus the type-driven custom
 typescript-eslint tooling, and this package to your dev dependencies:
 
 ```bash
-npm install --save-dev eslint typescript typescript-eslint eslint-plugin-jsdoc @sinemacula/coding-standards
+npm install --save-dev eslint typescript typescript-eslint eslint-plugin-jsdoc yaml-eslint-parser \
+    @sinemacula/coding-standards
 ```
 
+`yaml-eslint-parser` is imported by the base layer for the YAML comment-width block, so it has to resolve even in a
+repository with no YAML worth linting; without it the flat config fails to load at all.
+
 The package exposes three flat-config entry points:
 
 - `@sinemacula/coding-standards/js/eslint` - the base layer of syntax-only custom rules; needs no `tsconfig`, so it
-  stays cheap and runs anywhere Biome runs.
+  stays cheap and runs anywhere Biome runs. Covers `.ts`/`.js` and, for the comment-width rule alone, `.yml`/`.yaml`.
 - `@sinemacula/coding-standards/js/eslint/type-checked` - the opt-in type-aware layer. It includes the base layer and
   adds the cross-file / type-driven rules, so it needs a consumer `tsconfig`; use it in place of the base layer where
   one exists.
@@ -187,7 +191,10 @@ source-exported plugin definitions do not reliably propagate, so mirror it consu
 
 ```toml
 [plugins.definitions.eslint]
-package_filters = ["@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc"]
+package_filters = [
+    "@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc",
+    "yaml-eslint-parser",
+]
 ```
 
 Repositories enabling the Vue layer widen the same filter further, since its plugins have to resolve inside that sandbox
@@ -197,7 +204,7 @@ too:
 [plugins.definitions.eslint]
 package_filters = [
     "@sinemacula/coding-standards", "typescript-eslint", "@typescript-eslint", "eslint-plugin-jsdoc",
-    "eslint-plugin-vue", "vue-eslint-parser", "eslint-plugin-check-file",
+    "yaml-eslint-parser", "eslint-plugin-vue", "vue-eslint-parser", "eslint-plugin-check-file",
 ]
 ```
 
@@ -269,6 +276,7 @@ tag = "<version>"
 | `js/biome.json`                           | Biome                | JavaScript / TypeScript formatter + linter rules       |
 | `js/knip.json`                            | Knip                 | Unused-export detection rules                          |
 | `js/eslint/`                              | ESLint               | Structural, type-aware + Vue rules; runs with Biome    |
+| `js/eslint/` (YAML block)                 | ESLint               | Comment width in `.yml` / `.yaml`; yamllint owns rest  |
 | `markdown/.markdownlint.json`             | markdownlint         | Markdown linting rules                                 |
 | `yaml/.yamllint.yaml`                     | yamllint             | YAML linting rules                                     |
 | `shell/.shellcheckrc`                     | ShellCheck           | Shell script linting rules                             |
@@ -321,7 +329,7 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 ### ESLint rules
 
 All rules run in the base layer except `boolean-method-name`, which resolves return types and so requires the opt-in
-type-checked layer.
+type-checked layer. Every rule is scoped to `.ts`/`.js`; `comment-line-wrap` alone also runs over `.yml`/`.yaml`.
 
 | Rule                                           | Enforces                                                                            |
 |------------------------------------------------|-------------------------------------------------------------------------------------|
@@ -336,7 +344,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.           |
+| `@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
@@ -348,13 +356,21 @@ signatures and class fields holding a function take several. A data comment is n
 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. 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.
+`SineMacula.Commenting.CommentLineLength` sniff. It fills standalone `//` and `#` 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, machine-parsed tool directives (`eslint`, `biome-ignore`, `@ts-`, `Stryker`,
+`c8`/`v8`/`istanbul ignore`, `@vite-ignore`, `yamllint`, `yaml-language-server`, `renovate:` 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. Each
+comment token reclaims its own width from the line, so a `#` comment fills one column further than a `//` one.
+
+This is the one rule the base layer also carries over `.yml` and `.yaml`, which nothing else in the standards bounds for
+comment width: yamllint's `line-length` cannot tell a comment from a value, so it would fault `run:` commands and action
+refs nobody can shorten, and it has no autofix. The YAML block registers `yaml-eslint-parser` for its `#` comments and
+enables this rule alone - none of `eslint-plugin-yml`'s own rules are switched on, so YAML quoting, key order and
+indentation stay yamllint's business. Only standalone comments are reached: a block scalar's body is content rather
+than comment, so a shell comment inside a `run: |` step is never seen, and a comment trailing a value is not standalone.
 
 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/index.js

@@ -1,9 +1,11 @@
 import jsdoc from 'eslint-plugin-jsdoc';
 import tseslint from 'typescript-eslint';
+import * as yamlParser from 'yaml-eslint-parser';
 import plugin from './plugin.js';
 
 const TS_FILES = ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'];
 const TS_AND_JS_FILES = [...TS_FILES, '**/*.js', '**/*.jsx', '**/*.mjs', '**/*.cjs'];
+const YAML_FILES = ['**/*.yml', '**/*.yaml'];
 
 /**
  * Base flat config: the AST-only custom rules that need no type information.
@@ -12,7 +14,9 @@ const TS_AND_JS_FILES = [...TS_FILES, '**/*.js', '**/*.jsx', '**/*.mjs', '**/*.c
  * resolves TypeScript syntax. The interface, readonly-property and enum rules
  * target TypeScript-only constructs; no-mutable-static also applies to plain
  * JavaScript (exported let/var, mutable static fields), so it runs across both.
- * The opt-in type-aware layer lives in ./type-checked.js.
+ * A final block carries the comment-wrap rule alone over YAML, which otherwise
+ * bounds nothing about a comment's width. The opt-in type-aware layer lives in
+ * ./type-checked.js.
  *
  * @author      Ben Carey <bdmc@sinemacula.co.uk>
  * @copyright   2026 Sine Macula Limited
@@ -93,6 +97,23 @@ export default [
             'jsdoc/lines-before-block': ['error', { lines: 1, ignoreSingleLines: false }],
         },
     },
+    {
+        // YAML carries the comment-wrap rule and nothing else. The parser is
+        // registered for its `#` comments alone, so no eslint-plugin-yml rule
+        // is enabled: pulling that plugin's own set in would fault every
+        // consumer's YAML on quoting, key order and indentation at once, none
+        // of which this package governs. yamllint keeps the rest of YAML.
+        files: YAML_FILES,
+        plugins: {
+            '@sinemacula': plugin,
+        },
+        languageOptions: {
+            parser: yamlParser,
+        },
+        rules: {
+            '@sinemacula/comment-line-wrap': 'error',
+        },
+    },
     {
         files: ['**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}', '**/__tests__/**', '**/tests/**', '**/test-support/**'],
         rules: {

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

@@ -5,7 +5,10 @@
  * 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.
+ * meaning. The directive set spans the tools that read instructions out of a
+ * comment in any of the governed languages, YAML's included: a schema
+ * association or a Renovate manager hint is machine-read, so wrapping it would
+ * silently sever it from the key it annotates.
  *
  * @author      Ben Carey <bdmc@sinemacula.co.uk>
  * @copyright   2026 Sine Macula Limited
@@ -18,7 +21,7 @@ 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\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 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|yamllint\b|yaml-language-server\b|renovate:)/;
 const SEPARATOR = /^[=\-~*_#.+ ]{3,}$/;
 const CODE = new RegExp(`=>|->|::|;${WS}*$|\\{${WS}*$|^\\}|^(?:if|elseif|for|foreach|while|switch|catch)${WS}*\\(|^[\\w$>[\\]'.-]+${WS}*=[^=>]|^\\$`);
 const SPAN = /`[^`]*`|\{@[^}]*\}|\[[^\]]*\]\([^)]*\)/g;

package/js/eslint/rules/comment-line-wrap.js

@@ -6,6 +6,12 @@ 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]*)\*( ?)(.*)$/;
 
+/** The comment types a parser gives a line or block comment it recognises. */
+const COMMENT_TYPES = ['Line', 'Block'];
+
+/** The line-comment openers governed, matched longest first. */
+const LINE_TOKENS = ['//', '#'];
+
 /** Whether only whitespace precedes the comment on its own line. */
 function isStandalone(comment, sourceCode) {
     const line = sourceCode.lines[comment.loc.start.line - 1];
@@ -14,25 +20,44 @@ function isStandalone(comment, sourceCode) {
 }
 
 /**
- * Group standalone `//` comments into runs of adjacent lines sharing an indent,
- * so a wrapped paragraph is reflowed as one unit.
+ * The line-comment token a comment opens with, or null when it opens none.
+ *
+ * Read from the source text rather than inferred from the comment's type,
+ * because parsers label the same shape differently: a `//` comment arrives as
+ * `Line`, while yaml-eslint-parser tags a `#` comment `Block`. Requiring one of
+ * the two recognised types first leaves out a hashbang, which is neither and
+ * whose leading `#` must never be read as prose.
  */
-function slashRuns(comments, sourceCode) {
+function lineToken(comment, sourceCode) {
+    if (!COMMENT_TYPES.includes(comment.type)) {
+        return null;
+    }
+
+    const opener = sourceCode.text.slice(comment.range[0], comment.range[0] + 2);
+
+    return LINE_TOKENS.find(token => opener.startsWith(token)) ?? null;
+}
+
+/**
+ * Group standalone line comments into runs of adjacent lines sharing a token
+ * and an indent, so a wrapped paragraph is reflowed as one unit.
+ */
+function lineRuns(comments, sourceCode) {
     const runs = [];
     let current = null;
 
     for (const comment of comments) {
-        if (comment.type !== 'Line' || !isStandalone(comment, sourceCode)) {
+        const token = lineToken(comment, sourceCode);
+
+        if (token === null || !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);
+        if (current !== null && continues(current, comment, token)) {
+            current.comments.push(comment);
         } else {
-            current = [comment];
+            current = { token, comments: [comment] };
             runs.push(current);
         }
     }
@@ -40,22 +65,32 @@ function slashRuns(comments, sourceCode) {
     return runs;
 }
 
-/** Strip the single optional space that follows a `//` from a comment's value. */
-function slashContent(value) {
+/** Whether a comment extends the open run: same token, next line, same column. */
+function continues(run, comment, token) {
+    const last = run.comments[run.comments.length - 1];
+
+    return run.token === token
+        && comment.loc.start.line === last.loc.start.line + 1
+        && comment.loc.start.column === run.comments[0].loc.start.column;
+}
+
+/** Strip the single optional space that follows the token from a value. */
+function lineContent(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;
+/** Describe a line-comment run: content, margin, report locations and rebuild. */
+function lineDescriptor(run, sourceCode, eol) {
+    const { token, comments } = run;
+    const first = comments[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),
+        content: comments.map(comment => lineContent(comment.value)),
+        marginWidth: indent.length + token.length + 1,
+        locs: comments.map(comment => comment.loc),
+        range: [comments[0].range[0], comments[comments.length - 1].range[1]],
+        rebuild: lines => lines.map((line, offset) => `${offset === 0 ? '' : indent}${token}${line === '' ? '' : ` ${line}`}`).join(eol),
     };
 }
 
@@ -135,13 +170,19 @@ function enforce(context, descriptor, maxLength) {
  * 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.
+ * earlier than it needs to. Standalone runs of the line-comment tokens `//` and
+ * `#` 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.
+ *
+ * The `#` token carries the rule into YAML through yaml-eslint-parser, where it
+ * reaches only standalone comments: block-scalar bodies are content rather than
+ * comments, so a shell comment inside a `run:` step is never seen, and a
+ * comment trailing a value is not standalone. Each token reclaims its own
+ * width, so a `#` comment fills one column further than a `//` one.
  *
  * @author      Ben Carey <bdmc@sinemacula.co.uk>
  * @copyright   2026 Sine Macula Limited
@@ -181,8 +222,8 @@ export default createRule({
             Program() {
                 const comments = sourceCode.getAllComments();
 
-                for (const run of slashRuns(comments, sourceCode)) {
-                    enforce(context, slashDescriptor(run, sourceCode, eol), maxLength);
+                for (const run of lineRuns(comments, sourceCode)) {
+                    enforce(context, lineDescriptor(run, sourceCode, eol), maxLength);
                 }
 
                 for (const comment of comments) {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sinemacula/coding-standards",
-    "version": "1.20.2",
+    "version": "1.21.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>",
@@ -42,7 +42,7 @@
     },
     "scripts": {
         "test:js": "vitest run",
-        "lint:js": "eslint js/eslint"
+        "lint:js": "eslint ."
     },
     "devDependencies": {
         "@typescript-eslint/rule-tester": "^8.0.0",
@@ -54,7 +54,8 @@
         "typescript": "^5.0.0",
         "typescript-eslint": "^8.0.0",
         "vitest": "^3.0.0",
-        "vue-eslint-parser": "^10.0.0"
+        "vue-eslint-parser": "^10.0.0",
+        "yaml-eslint-parser": "^2.1.0"
     },
     "peerDependencies": {
         "eslint": ">=9",
@@ -63,7 +64,8 @@
         "eslint-plugin-vue": ">=10",
         "typescript": ">=4.8.4",
         "typescript-eslint": "^8",
-        "vue-eslint-parser": ">=10"
+        "vue-eslint-parser": ">=10",
+        "yaml-eslint-parser": ">=2"
     },
     "peerDependenciesMeta": {
         "eslint": {
@@ -86,6 +88,9 @@
         },
         "vue-eslint-parser": {
             "optional": true
+        },
+        "yaml-eslint-parser": {
+            "optional": true
         }
     },
     "publishConfig": {