@sinemacula/coding-standards 1.20.2 → 1.22.0

package/README.md

@@ -26,8 +26,13 @@ composer require --dev sinemacula/coding-standards
 npm install --save-dev @sinemacula/coding-standards
 ```
 
-The npm package ships only the static configs (`js/`, `markdown/`, `yaml/`, `shell/`, `security/`). The PHP autoloaded
-code lives in the Composer package.
+The npm package ships only the static configs (`js/`, `markdown/`, `yaml/`, `shell/`, `security/`, `swift/`). The PHP
+autoloaded code lives in the Composer package.
+
+### Qlty (Swift-side: SwiftLint, SwiftFormat)
+
+Swift consumers do not need the Composer or npm package. Qlty fetches the shared Swift configs from this repository as
+a pinned source and installs the native tools on macOS.
 
 ## Usage
 
@@ -74,16 +79,19 @@ The `SineMacula` coding standard is auto-discovered via the `phpcodesniffer-stan
 ### PHPStan
 
 The shared PHPStan configs are auto-included via the `extra.phpstan.includes` section in `composer.json`. Your project's
-`phpstan.neon` only needs project-specific settings:
+`phpstan.neon` only needs its paths:
 
 ```neon
 parameters:
-    level: 8
     paths:
         - src
         - tests
 ```
 
+Do not set `level`. Analysis runs through qlty, whose phpstan driver passes `--level=9` on the command line, and a
+command-line level overrides the config file outright - so a level set here does nothing except mislead whoever reads
+it next.
+
 The base config enables PHPStan's checked-exception analysis: every exception a method can throw must appear in its
 `@throws` tag, except a configured set of programming-error and infrastructure exceptions that stay unchecked - the
 `LogicException`, `RuntimeException` and `Error` families among them (see `php/phpstan-base.neon` for the full list).
@@ -130,13 +138,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 +199,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 +212,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",
 ]
 ```
 
@@ -258,6 +273,70 @@ repository = "https://github.com/sinemacula/coding-standards"
 tag = "<version>"
 ```
 
+### Swift (SwiftLint and SwiftFormat)
+
+Swift repositories consume the shared policy through Qlty. Enable the default source for the tools, this repository
+for the exported configs, and both native plugins:
+
+```toml
+config_version = "0"
+
+# SwiftLint's own `excluded:` list only applies when it walks a directory. Qlty
+# passes explicit file paths, so generated and third-party sources have to be
+# excluded here or the shared policy is reported against machine-written code.
+exclude_patterns = [
+    ".build/**",
+    "build/**",
+    "DerivedData/**",
+    "Carthage/**",
+    "Pods/**",
+    "vendor/**",
+    "**/Generated/**",
+]
+
+test_patterns = [
+    "**/*Tests.swift",
+    "**/Tests/**",
+]
+
+[[source]]
+name = "default"
+default = true
+
+[[source]]
+name = "sinemacula"
+repository = "https://github.com/sinemacula/coding-standards"
+tag = "<version>"
+
+[[plugin]]
+name = "swiftlint"
+
+[[plugin]]
+name = "swiftformat"
+mode = "comment"
+```
+
+This is the same configuration the package's own integration test runs, so what is documented here is what CI exercises.
+
+Run formatting and linting locally:
+
+```bash
+qlty fmt --all
+qlty check --all
+```
+
+SwiftLint and SwiftFormat are native macOS plugins. Qlty Cloud's Linux workers cannot execute them, so every Swift
+consumer needs a macOS CI job that verifies formatting and runs `qlty check`. Qlty Cloud still provides its built-in
+Swift maintainability, duplication, complexity, security, and coverage capabilities.
+
+The shared policy targets Swift 6 and deliberately contains no application-specific include paths or architecture
+rules. Xcode compiler checks such as strict concurrency, warnings-as-errors, platform availability, and test builds
+remain the consuming project's responsibility.
+
+SwiftLint has no configuration inheritance. A `.swiftlint.yml` committed to a consuming repository *replaces* the
+shared policy rather than extending it, so adding one to relax a single rule silently discards the whole standard.
+Raise a pull request here instead, or copy the shared file wholesale and edit the copy.
+
 ## What's Included
 
 | Path                                      | Tool                 | Description                                            |
@@ -269,11 +348,14 @@ 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                             |
 | `security/.gitleaks.toml`                 | Gitleaks             | Secret-detection ruleset                               |
 | `editorconfig/.editorconfig-checker.json` | editorconfig-checker | Disables only the max-line-length check                |
+| `swift/.swiftlint.yml`                    | SwiftLint            | Shared Swift 6 lint, safety, concurrency, and metrics  |
+| `swift/.swiftformat`                      | SwiftFormat          | Shared deterministic Swift 6 formatting policy         |
 
 ## Rules
 
@@ -298,7 +380,7 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 | `SineMacula.Commenting.SingleLineMemberComment`            | A property, constant or enum-case doc comment sits on one line.             |
 | `SineMacula.Exceptions.DisallowBaseException`              | No throwing the base `\Exception`; throw a domain exception.                |
 | `SineMacula.Exceptions.RequireEmptyCatchComment`           | An empty catch block must comment its intentional swallow.                  |
-| `SineMacula.Functions.RequireSensitiveParameter`           | Secret-named params need `#[\SensitiveParameter]`.                          |
+| `SineMacula.Functions.RequireSensitiveParameter`           | Secret-named params need `#[\SensitiveParameter]`; object types exempt.     |
 | `SineMacula.Metrics.MaxMethodCount`                        | A class/interface/trait/enum may declare at most 20 methods (tests exempt). |
 | `SineMacula.Metrics.MethodLength`                          | A method body may have at most 50 significant lines (tests exempt).         |
 | `SineMacula.Namespaces.RequireConcernsNamespace`           | Traits must live under a `Concerns` namespace segment.                      |
@@ -313,15 +395,17 @@ native directive - `// phpcs:ignore <code>` for a sniff, `@phpstan-ignore <ident
 
 ### PHPStan rules
 
-| Identifier                         | Enforces                                                             |
-|------------------------------------|----------------------------------------------------------------------|
-| `sineMacula.mutableStaticProperty` | Static properties written at runtime; `@managed-static` opts out.    |
-| `sineMacula.readonlyClass`         | A final class with only readonly properties must be `readonly`.      |
+| Identifier                             | Enforces                                                                       |
+|----------------------------------------|--------------------------------------------------------------------------------|
+| `sineMacula.mutableStaticProperty`     | Static properties written at runtime; `@managed-static` opts out.              |
+| `sineMacula.readonlyClass`             | A final class with only readonly properties must be `readonly`.                |
+| `sineMacula.redundantStaticReference`  | In a final class, `new static`, `static::` and `instanceof static` are `self`. |
+| `sineMacula.redundantStaticReturnType` | In a final class, a `static` return type or `@return` must be `self`.          |
 
 ### 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 +420,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,26 +432,122 @@ 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)
 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
-`@typescript-eslint/only-throw-error`.
+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`.
+
+`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
+and is free to drift; plain JavaScript has no signature to hold one, which makes the tag the only place a type is
+written down, and clearing it there would delete the type rather than move it. The description rules are not scoped
+that way: a tag says what a value means whether or not it also says what the value is, so `@param` and `@returns` need
+a description in both languages.
+
+### Swift policy
+
+SwiftLint keeps its default rule set and adds curated opt-in rules with a strong correctness, concurrency, safety,
+performance, or readability signal. The policy intentionally avoids analyzer-only rules, which need an Xcode compiler
+log and cannot run through Qlty's normal lint driver.
+
+Notable additions include checks for force-unwrapping, silently discarded throwing tasks, invalid concurrency
+annotations, unsafe optional modelling, empty XCTest methods, unbalanced access control, inefficient collection
+operations, oversized closures, and non-private SwiftUI state. A discarded throwing task is an error because it can
+silently lose an operational failure; most style and maintainability findings retain warning severity.
+
+The main review and hard ceilings are:
+
+| Metric                | Warning | Error |
+|-----------------------|--------:|------:|
+| Line length           |     120 |   160 |
+| File length           |     500 |   800 |
+| Type body length      |     300 |   500 |
+| Function body length  |      50 |    80 |
+| Closure body length   |      50 |    80 |
+| Cyclomatic complexity |      10 |    20 |
+| Function parameters   |       6 |     8 |
+
+SwiftFormat owns whitespace, wrapping, imports, and other mechanically correctable layout. Its configuration matches
+SwiftLint on 120-column wrapping, import ordering, and no trailing commas, and it is the only tool of the two that
+enforces four-space indentation.
+
+The policy also carries over the documentation opinions the PHP and TypeScript standards enforce:
+
+- `file_header` requires a copyright header, as `RequireCopyrightTagSniff` does for PHP classes and `require-copyright`
+  does for TypeScript declarations. The pattern asserts only that the tag is present, so the holder, year and format
+  stay the consuming project's choice, and SwiftFormat's `--header ignore` leaves an existing header untouched.
+- `missing_docs` requires documentation on `open` and `public` declarations, the Swift equivalent of the PHP docblock
+  sniffs and `jsdoc/require-jsdoc`. It is scoped to the public surface deliberately: demanding a comment on every
+  internal member would generate noise the other two standards do not.
+- `line_length` holds comments to the limit rather than exempting them. SwiftFormat wraps `//` comments to 120 but
+  leaves `///` doc comments alone, so without this an over-long documentation line passes both tools - where PHP and
+  TypeScript both wrap comment prose. Rules that can alter ownership,
+control flow, explicit `Sendable` conformance, or public API shape are disabled; those changes require human review.
+
+### Methods that only throw
+
+A method that exists solely to refuse - a `__serialize()` that throws so a value holding a secret cannot reach a queue
+payload or a cache entry - returns nothing on any path, and `never` is how to say so:
+
+```php
+/**
+ * @throws \LogicException
+ *
+ * @return never
+ */
+public function __serialize(): never
+{
+    throw new LogicException('A token must not be serialised.');
+}
+```
+
+`never` is a subtype of every return type, so narrowing to it always satisfies an inherited signature, a magic method's
+expected return included. The one place it does not fit is a method a subclass is meant to return from, because a child
+cannot widen `never` back. Such a method keeps the type it declares and throws anyway, which needs no directive:
+
+```php
+/**
+ * @throws \LogicException
+ *
+ * @return array<int, string>
+ */
+public function build(): array
+{
+    throw new LogicException('Not implemented.');
+}
+```
+
+Whether a documented return is ever produced is a question of control flow, not of tokens, so no sniff here asks it -
+`Squiz.Commenting.FunctionComment.InvalidNoReturn` decides by looking for a `return` token and so faults exactly the
+guard above. PHPStan's `return.missing` answers it properly: it reports a method that can reach its end without
+returning the type it documents, and stays quiet where every path throws.
+
+The one thing still worth knowing is that spelling out the contained type of a documented traversable can drag in
+`mixed`, which the mixed ban faults on its own footing and which has its own directive.
 
 ## Requirements
 
 - PHP ^8.3 (Composer package)
 - Node.js (npm package)
+- macOS and Qlty CLI (SwiftLint and SwiftFormat policy)
 
 ## Testing
 
@@ -380,6 +560,7 @@ composer analyse             # PHPStan static analysis
 composer check               # static analysis and lint via qlty
 composer format              # format via qlty
 composer smells              # duplication / complexity smells via qlty
+bash scripts/test-swift-policy.sh # exported Swift policy integration test (macOS)
 ```
 
 ## Changelog

package/js/eslint/index.js

@@ -1,18 +1,23 @@
 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.
  *
  * Requires no tsconfig, so it stays cheap. The typescript-eslint parser
  * 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.
+ * target TypeScript-only constructs, as does jsdoc/no-types, which presumes a
+ * signature to hold the type it strips from the tag; no-mutable-static also
+ * applies to plain JavaScript (exported let/var, mutable static fields), so it
+ * runs across both. 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
@@ -23,6 +28,7 @@ export default [
         plugins: {
             '@sinemacula': plugin,
             '@typescript-eslint': tseslint.plugin,
+            jsdoc,
         },
         languageOptions: {
             parser: tseslint.parser,
@@ -33,6 +39,14 @@ export default [
             '@sinemacula/valid-enum-member-name': 'error',
 
             '@typescript-eslint/no-explicit-any': 'error',
+
+            // A TypeScript signature already records the type, so a tag that
+            // repeats it is a second copy free to drift from the first. Plain
+            // JavaScript has no signature to hold one, which is why this rule
+            // stops at TypeScript: there the tag is the only place a type is
+            // written down, and clearing it would delete the type rather than
+            // move it to where the reader already looks.
+            'jsdoc/no-types': 'error',
         },
     },
     {
@@ -62,10 +76,11 @@ export default [
             // property carries a documentation comment describing intent, so a
             // reader meets each member's purpose before its type. Interface
             // members and class fields are held to the same bar as methods.
-            // 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.
+            // Every @param and @returns says what the value means, whether or
+            // not the tag also carries a type; the type itself is governed by
+            // no-types in the TypeScript block above, which is the only place a
+            // signature holds one. Each block stands off from the code above
+            // it, single-line blocks included.
             'jsdoc/require-jsdoc': ['error', {
                 require: {
                     ClassDeclaration: true,
@@ -87,12 +102,28 @@ export default [
                 enableFixer: false,
             }],
             'jsdoc/require-description': 'error',
-            'jsdoc/no-types': 'error',
             'jsdoc/require-param-description': 'error',
             'jsdoc/require-returns-description': 'error',
             '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/boolean-method-name.js

@@ -140,22 +140,36 @@ function hasImperativeTag(sourceCode, docHost, nameNode) {
     return false;
 }
 
+/**
+ * Whether the name is outside the rule's reach: a magic member, a name that
+ * already reads as a predicate, a command or event handler, a well-known type
+ * accessor, or a member carrying the @imperative opt-out tag.
+ */
+function isExempt(state, nameNode, name, docHost) {
+    if (name.startsWith('__') || TYPE_ACCESSOR_NAMES.has(name)) {
+        return true;
+    }
+
+    if (isPredicate(name, state.prefixes, state.predicates)) {
+        return true;
+    }
+
+    if (isCommandVerb(name, state.commandVerbs) || isEventHandler(name)) {
+        return true;
+    }
+
+    return hasImperativeTag(state.sourceCode, docHost, nameNode);
+}
+
 /**
  * Report the name when it neither reads as a predicate nor is exempt and the
  * resolved (awaited) return type is boolean. Type-predicate guards are
  * predicates by structure and left alone.
  */
 function inspect(state, nameNode, name, fnNode, docHost) {
-    const { checker, services, context, sourceCode } = state;
-
-    if (
-        name.startsWith('__')
-        || isPredicate(name, state.prefixes, state.predicates)
-        || isCommandVerb(name, state.commandVerbs)
-        || isEventHandler(name)
-        || TYPE_ACCESSOR_NAMES.has(name)
-        || hasImperativeTag(sourceCode, docHost, nameNode)
-    ) {
+    const { checker, services, context } = state;
+
+    if (isExempt(state, nameNode, name, docHost)) {
         return;
     }
 

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.22.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>",
@@ -16,6 +16,9 @@
         "biome",
         "knip",
         "eslint",
+        "swift",
+        "swiftformat",
+        "swiftlint",
         "typescript",
         "coding-standards",
         "linting",
@@ -28,9 +31,11 @@
         "yaml/",
         "shell/",
         "security/",
+        "swift/",
         "README.md",
         "LICENSE",
         "NOTICE",
+        "!js/eslint/__tests__",
         "!js/eslint/rules/__tests__"
     ],
     "exports": {
@@ -42,7 +47,7 @@
     },
     "scripts": {
         "test:js": "vitest run",
-        "lint:js": "eslint js/eslint"
+        "lint:js": "eslint ."
     },
     "devDependencies": {
         "@typescript-eslint/rule-tester": "^8.0.0",
@@ -54,7 +59,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 +69,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 +93,9 @@
         },
         "vue-eslint-parser": {
             "optional": true
+        },
+        "yaml-eslint-parser": {
+            "optional": true
         }
     },
     "publishConfig": {

package/swift/.swiftformat

@@ -0,0 +1,48 @@
+# Shared Swift 6 formatting policy for Sine Macula applications and packages.
+
+--swiftversion 6.0
+--indent 4
+--linebreaks lf
+--maxwidth 120
+--trim-whitespace always
+--xcode-indentation enabled
+
+# Keep multiline declarations deterministic and easy to diff.
+--wrap-arguments before-first
+--wrap-parameters before-first
+--wrap-collections before-first
+--wrap-conditions before-first
+--wrap-effects if-multiline
+--wrap-return-type if-multiline
+--closing-paren balanced
+--call-site-paren balanced
+
+# Match SwiftLint and avoid formatter/linter churn. SwiftLint's sorted_imports
+# orders imports by module name alone, while SwiftFormat defaults to grouping by
+# access level first (access-control,alpha). On a file using Swift 6 access-level
+# imports that disagreement makes `qlty fmt` emit an order `qlty check` rejects,
+# and re-running the formatter never settles it.
+--import-grouping alpha
+--trailing-commas never
+--semicolons never
+--self remove
+--ifdef no-indent
+
+# SwiftLint's file_header rule owns the copyright header. `ignore` leaves an
+# existing header alone rather than rewriting every file to one template, so the
+# holder and format stay the consuming project's choice.
+--header ignore
+
+# Do not rewrite public function signatures just because an implementation
+# does not currently use an argument. Removing unused closure arguments is
+# local and cannot alter a declared API.
+--strip-unused-args closure-only
+
+# Formatting must not change ownership, control flow, or API shape.
+--anonymous-for-each ignore
+--disable enumNamespaces,initCoderUnavailable,preferForLoop,redundantSendable,strongOutlets
+
+# Mirror the exclusions in .swiftlint.yml. SwiftFormat rewrites files in place,
+# and unlike SwiftLint's `excluded:` it honours these even when a path is passed
+# explicitly - so generated and third-party code is protected under Qlty too.
+--exclude .build,build,DerivedData,Carthage,Pods,vendor,**/Generated

package/swift/.swiftlint.yml

@@ -0,0 +1,211 @@
+# Shared Swift 6 lint policy for Sine Macula applications and packages.
+#
+# Consumer-specific include paths do not belong here. Qlty determines the files
+# passed to SwiftLint, while the exclusions below protect direct CLI and Xcode
+# build-phase usage from generated and third-party code.
+#
+# Note that SwiftLint applies `excluded:` only when it walks a directory itself.
+# Qlty passes explicit file paths, so a consumer must also exclude generated and
+# third-party sources via `exclude_patterns` in its own .qlty/qlty.toml.
+
+excluded:
+  - .build
+  - build
+  - DerivedData
+  - Carthage
+  - Pods
+  - vendor
+  - "**/Generated"
+  - "**/Generated/**"
+
+reporter: xcode
+
+# SwiftLint's default rules remain enabled. These opt-in rules add checks with a
+# strong correctness, concurrency, safety, performance, or readability signal
+# without requiring a particular application architecture.
+opt_in_rules:
+  - accessibility_label_for_image
+  - accessibility_trait_for_button
+  - anonymous_argument_in_multiline_closure
+  - array_init
+  - closure_body_length
+  - closure_spacing
+  - collection_alignment
+  - contains_over_filter_count
+  - contains_over_filter_is_empty
+  - contains_over_first_not_nil
+  - contains_over_range_nil_comparison
+  - convenience_type
+  - direct_return
+  - discarded_notification_center_observer
+  - discouraged_assert
+  - discouraged_none_name
+  - discouraged_optional_boolean
+  - discouraged_optional_collection
+  - empty_collection_literal
+  - empty_count
+  - empty_string
+  - empty_xctest_method
+  - enum_case_associated_values_count
+  - expiring_todo
+  - explicit_init
+  - fallthrough
+  - fatal_error_message
+  - final_test_case
+  - first_where
+  - flatmap_over_map_reduce
+  - force_unwrapping
+  - function_default_parameter_at_end
+  - identical_operands
+  - implicitly_unwrapped_optional
+  - incompatible_concurrency_annotation
+  - joined_default_parameter
+  - last_where
+  - literal_expression_end_indentation
+  - local_doc_comment
+  - lower_acl_than_parent
+  - file_header
+  - missing_docs
+  - modifier_order
+  - no_empty_block
+  - non_overridable_class_declaration
+  - optional_enum_case_matching
+  - override_in_extension
+  - pattern_matching_keywords
+  - prefer_condition_list
+  - prefer_key_path
+  - prefer_self_in_static_references
+  - prefer_self_type_over_type_of_self
+  - prefer_zero_over_explicit_init
+  - private_subject
+  - private_swiftui_state
+  - reduce_into
+  - redundant_nil_coalescing
+  - redundant_type_annotation
+  - return_value_from_void_function
+  - shorthand_argument
+  - shorthand_optional_binding
+  - sorted_first_last
+  - sorted_imports
+  - static_operator
+  - strict_fileprivate
+  - superfluous_else
+  - test_case_accessibility
+  - toggle_bool
+  - unavailable_function
+  - unhandled_throwing_task
+  - unneeded_parentheses_in_closure_argument
+  - unowned_variable_capture
+  - untyped_error_in_catch
+  - unused_parameter
+  - variable_shadowing
+  - weak_delegate
+  - xct_specific_matcher
+  - yoda_condition
+
+# Thresholds intentionally distinguish a review signal from a hard ceiling. Qlty
+# preserves the warning/error severity in its findings.
+closure_body_length:
+  warning: 50
+  error: 80
+
+cyclomatic_complexity:
+  warning: 10
+  error: 20
+  ignores_case_statements: false
+
+enum_case_associated_values_count:
+  warning: 5
+  error: 6
+
+file_length:
+  warning: 500
+  error: 800
+  ignore_comment_only_lines: true
+
+function_body_length:
+  warning: 50
+  error: 80
+
+function_parameter_count:
+  warning: 6
+  error: 8
+  ignores_default_parameters: true
+
+identifier_name:
+  min_length:
+    warning: 3
+    error: 2
+  max_length:
+    warning: 50
+    error: 60
+  excluded:
+    - id
+    - x
+    - y
+
+line_length:
+  warning: 120
+  error: 160
+  ignores_urls: true
+  ignores_function_declarations: false
+  # SwiftFormat wraps `//` comments to this width but leaves `///` doc comments
+  # alone, so exempting comments here would let an over-long documentation line
+  # pass both tools. PHP and TypeScript hold comments to the limit too.
+  ignores_comments: false
+  ignores_interpolated_strings: true
+  ignores_multiline_strings: true
+  ignores_regex_literals: true
+
+nesting:
+  type_level:
+    warning: 2
+  function_level:
+    warning: 3
+  check_nesting_in_closures_and_statements: true
+  always_allow_one_type_in_functions: false
+  ignore_typealiases_and_associatedtypes: true
+  ignore_coding_keys: true
+
+type_body_length:
+  warning: 300
+  error: 500
+  excluded_types:
+    - extension
+    - protocol
+
+type_name:
+  min_length:
+    warning: 3
+    error: 2
+  max_length:
+    warning: 50
+    error: 60
+
+# Match SwiftFormat's explicit no-trailing-comma policy.
+trailing_comma:
+  mandatory_comma: false
+
+# The PHP standard requires an @copyright tag in every class docblock and the
+# TypeScript standard requires @copyright and @author, so a Swift file carries a
+# copyright header too. The pattern deliberately asserts only that the tag is
+# present: the holder, year and format stay the consuming project's to choose,
+# and SwiftFormat's `--header ignore` leaves an existing header untouched rather
+# than rewriting it to a template.
+file_header:
+  required_pattern: '(?:\/\/|\/\*)(?s:.)*[Cc]opyright(?s:.)*'
+
+# PHP requires a docblock on every class and method, TypeScript requires a JSDoc
+# block with a description. Swift's equivalent is held to the public surface:
+# `open` and `public` declarations are the API a consumer reads, and demanding a
+# comment on every internal member would be noise the other two standards do not
+# generate either.
+missing_docs:
+  warning: [open, public]
+  excludes_extensions: true
+  excludes_inherited_types: true
+  excludes_trivial_init: true
+
+# A discarded throwing task can silently lose an operational failure.
+unhandled_throwing_task:
+  severity: error

package/swift/README.md

@@ -0,0 +1,35 @@
+# Swift standards
+
+The shared Swift 6 policy consists of:
+
+- `.swiftlint.yml` for correctness, concurrency, safety, performance, metrics, and style findings.
+- `.swiftformat` for deterministic source formatting.
+
+Both tools are provided by Qlty's default source. Consumers enable the `swiftlint` and `swiftformat` plugins and receive
+these configurations from the Sine Macula source declared in `.qlty/qlty.toml`.
+
+SwiftLint and SwiftFormat run through Qlty CLI only on macOS. Qlty Cloud still provides Swift maintainability analysis,
+but its Linux workers cannot execute these two native plugins. A Swift repository therefore needs a macOS quality job
+that runs both `qlty fmt --all` and `qlty check --all`.
+
+The policy is not purely stock SwiftLint. Where the PHP and TypeScript standards in this repository express a house
+opinion that SwiftLint can express too, it is carried over: a required copyright header (`file_header`), documentation
+on the public surface (`missing_docs`), and comment prose held to the line limit. Opinions with no SwiftLint
+equivalent - a maximum method count per type, protocol and boolean-method naming, and a required-readonly property
+rule - are not enforced for Swift, and closing those would mean writing custom regex rules.
+
+Application-specific paths, generated-source conventions, and architectural restrictions stay in the consuming
+repository. The shared policy must remain usable by macOS apps, iOS apps, command-line tools, and Swift packages.
+
+The standard deliberately avoids formatter rules that can change ownership, control flow, or an API declaration. A
+formatter should make an equivalent program consistent; correctness and design changes belong in reviewed source
+edits.
+
+## Deliberately not included
+
+- StringsLint is deferred because its current Qlty integration does not support modern `.xcstrings` String Catalogs.
+  Reconsider it for a consumer that deliberately uses legacy `.strings` or `.stringsdict` resources.
+- Semgrep rules belong here only after an organization-wide Swift security or architecture rule is defined. Product-
+  specific boundaries should stay in the product repository.
+- Compiler-enforced policy such as strict concurrency, warnings-as-errors, deployment targets, and platform
+  availability remains in each Xcode project or shared project template; Qlty is not a substitute for `xcodebuild`.