@sinemacula/coding-standards 1.21.0 → 1.23.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).
@@ -265,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                                            |
@@ -282,6 +354,8 @@ tag = "<version>"
 | `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
 
@@ -306,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.                      |
@@ -321,10 +395,12 @@ 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
 
@@ -341,19 +417,30 @@ type-checked layer. Every rule is scoped to `.ts`/`.js`; `comment-line-wrap` alo
 | `@sinemacula/max-methods-per-class`            | A single class may declare at most 20 methods; test code exempt.                    |
 | `@sinemacula/no-base-error`                    | Throw a domain-specific `Error` subclass, never the base `Error`; test code exempt. |
 | `@sinemacula/require-copyright`                | Every file must carry a documentation comment with `@copyright` and `@author`.      |
+| `@sinemacula/require-file-description`         | The same comment must open with a prose summary above those tags.                   |
 | `@sinemacula/align-doc-tags`                   | `@author` and `@copyright` values line up at a single column; autofixable.          |
 | `@sinemacula/single-line-property-doc`         | A data member's documentation comment sits on one line; autofixable.                |
 | `@sinemacula/multiline-function-doc`           | A method's documentation comment spans multiple lines; autofixable.                 |
 | `@sinemacula/comment-line-wrap`                | Standalone comment prose wrapped to 80 chars, YAML included; premature wraps too.   |
 
-`boolean-method-name` takes `additionalPrefixes`, `additionalPredicates` and `additionalCommandVerbs` (string arrays)
-to widen the accepted vocabulary from a consumer config. `max-methods-per-class` takes `max`, `no-base-error` takes
-`allow`, and `require-copyright` takes `tags` to adjust their defaults. `align-doc-tags` takes `tags` and `column`, the
-column counting from the `@`, so the default of 14 gives `@author` six spaces and `@copyright` three. Together
-`single-line-property-doc` and `multiline-function-doc` set a member's comment shape by its kind: data members
-(interface property signatures, enum members and data class fields) take one line, while methods, interface method
-signatures and class fields holding a function take several. A data comment is never required, only held to one line
-where present; a free function keeps the freedom of either shape.
+`boolean-method-name` takes `additionalPrefixes`, `additionalPredicates` and `additionalCommandVerbs` (string arrays) to
+widen the accepted vocabulary from a consumer config. `max-methods-per-class` takes `max`, `no-base-error` takes
+`allow`, and `require-copyright` and `require-file-description` each take `tags` to adjust their defaults.
+`align-doc-tags` takes `tags` and `column`, the column counting from the `@`, so the default of 14 gives `@author` six
+spaces and `@copyright` three. Together `single-line-property-doc` and `multiline-function-doc` set a member's comment
+shape by its kind: data members (interface property signatures, enum members and data class fields) take one line, while
+methods, interface method signatures and class fields holding a function take several. A data comment is never required,
+only held to one line where present; a free function keeps the freedom of either shape.
+
+`require-copyright` and `require-file-description` divide the file header between them: the first asks that a single
+block comment carry `@copyright` and `@author`, the second that the same block open with a prose summary above them,
+which is the shape the convention has always described and the half nothing enforced. Both find that block by the
+tags it carries rather than by its position, so a module documented at its export below the imports is read as the
+header exactly as a comment at the top of the file is; a project that narrows one rule's `tags` should narrow the
+other's to match. Only the block's first non-blank line is read, and only for whether it is prose rather than a tag,
+which puts the summary above the tags and stops a wrapped tag value's continuation line passing as one. What the
+summary says is the author's business. A file carrying no such block at all is left to `require-copyright`, so one
+missing header is never faulted twice.
 
 `comment-line-wrap` takes `maxLength` (default 80) and is the syntax-only counterpart of the PHP
 `SineMacula.Commenting.CommentLineLength` sniff. It fills standalone `//` and `#` runs and multi-line docblock prose
@@ -374,16 +461,112 @@ than comment, so a shell comment inside a `run: |` step is never seen, and a com
 
 The base layer also switches on a set of built-in rules: `@typescript-eslint/no-explicit-any`, `curly` (a brace on every
 control statement, as PSR-12 already requires on the PHP side), `max-lines-per-function` (50 lines, test code exempt)
-and `max-depth` (4), plus `eslint-plugin-jsdoc` rules that require a documentation comment on every declared function,
-method, class, interface member and class field, 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`.
+and `max-depth` (4, test code exempt), plus `eslint-plugin-jsdoc` rules that require a documentation comment on every
+declared function, method, class, interface member and class field, require a description on every `@param` and
+`@returns`, and keep a blank line above every documentation block, single-line blocks included. The type-checked layer
+adds `@typescript-eslint/explicit-module-boundary-types` and `@typescript-eslint/only-throw-error`.
+
+Test files - `*.test.*`, `*.spec.*` and anything under `__tests__/`, `tests/` or `test-support/` - are exempt from
+`max-lines-per-function` and `max-depth` alone. A spec body is a long, deeply nested account of one scenario, and
+splitting it to satisfy a metric hides the scenario rather than simplifying it. They are not exempt from documentation:
+`jsdoc/require-jsdoc` reaches declared functions, assigned arrows and classes, which in a spec file are its helpers,
+factories and builders - the code a reader has to understand before the assertions mean anything. A test case is an
+arrow passed as a call argument, which none of the rule's contexts match, so `it('...', () => {})` is never asked to
+carry a block; a spec of test cases alone carries no documentation burden at all.
+
+`jsdoc/no-types`, which forbids a type in `@param`/`@returns`, runs over `.ts`/`.tsx`/`.mts`/`.cts` alone, alongside
+`@typescript-eslint/no-explicit-any`. A TypeScript signature already records the type, so the tag would only repeat it
+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
 
@@ -396,6 +579,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

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

package/js/eslint/plugin.js

@@ -7,6 +7,7 @@ import noBaseError from './rules/no-base-error.js';
 import noInterfacePrefix from './rules/no-interface-prefix.js';
 import noMutableStatic from './rules/no-mutable-static.js';
 import requireCopyright from './rules/require-copyright.js';
+import requireFileDescription from './rules/require-file-description.js';
 import requireReadonlyPublicProperty from './rules/require-readonly-public-property.js';
 import singleLinePropertyDoc from './rules/single-line-property-doc.js';
 import validEnumMemberName from './rules/valid-enum-member-name.js';
@@ -34,6 +35,7 @@ export default {
         'max-methods-per-class': maxMethodsPerClass,
         'no-base-error': noBaseError,
         'require-copyright': requireCopyright,
+        'require-file-description': requireFileDescription,
         'align-doc-tags': alignDocTags,
         'single-line-property-doc': singleLinePropertyDoc,
         'multiline-function-doc': multilineFunctionDoc,

package/js/eslint/rules/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/lib.js

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

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

@@ -1,14 +1,7 @@
-import { createRule } from './lib.js';
+import { createRule, fileDocBlock } from './lib.js';
 
 const DEFAULT_TAGS = ['copyright', 'author'];
 
-/** A boundary-anchored matcher for a documentation tag by its bare name. */
-function tagMatcher(tag) {
-    const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
-    return new RegExp(`(?:^|[\\s*])@${escaped}(?![-\\w])`, 'i');
-}
-
 /**
  * Require a documentation comment carrying the tags every source file must
  * declare, `@copyright` and `@author` by default.
@@ -17,7 +10,9 @@ function tagMatcher(tag) {
  * sit inside the file's descriptive docblock alongside its summary rather than
  * in a separate header. Only the presence of each tag is checked, never its
  * value or alignment, which are matters of formatting. The required set is
- * configurable, so a project may drop `@author` or add tags of its own.
+ * configurable, so a project may drop `@author` or add tags of its own. The
+ * summary those tags sit beside is the separate concern of
+ * `require-file-description`, which locates the same block by the same tags.
  *
  * @author      Ben Carey <bdmc@sinemacula.co.uk>
  * @copyright   2026 Sine Macula Limited
@@ -49,15 +44,10 @@ export default createRule({
     create(context, [options]) {
         const { sourceCode } = context;
         const required = options.tags ?? DEFAULT_TAGS;
-        const matchers = required.map(tagMatcher);
 
         return {
             Program(node) {
-                const documented = sourceCode.getAllComments().some(
-                    comment => comment.type === 'Block' && matchers.every(matcher => matcher.test(comment.value)),
-                );
-
-                if (documented) {
+                if (fileDocBlock(sourceCode, required) !== null) {
                     return;
                 }
 

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sinemacula/coding-standards",
-    "version": "1.21.0",
+    "version": "1.23.0",
     "description": "Centralized coding standards, static analysis configurations, and code quality tooling for all Sine Macula repositories.",
     "license": "Apache-2.0",
     "author": "Ben Carey <bdmc@sinemacula.co.uk>",
@@ -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": {
@@ -53,7 +58,7 @@
         "eslint-plugin-vue": "^10.0.0",
         "typescript": "^5.0.0",
         "typescript-eslint": "^8.0.0",
-        "vitest": "^3.0.0",
+        "vitest": "^4.1.11",
         "vue-eslint-parser": "^10.0.0",
         "yaml-eslint-parser": "^2.1.0"
     },

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`.