@sinemacula/coding-standards 1.21.0 → 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).
@@ -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
 
@@ -375,15 +451,103 @@ 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`.
+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
 
@@ -396,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

@@ -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',
         },
     },
     {
@@ -66,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,
@@ -91,7 +102,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 }],

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/package.json

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

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