@gspothq/cli 0.0.0-stage → 0.1.1

package/configurations/language/sql/manifest.toml

@@ -0,0 +1,68 @@
+allowed_words = ["SQL"]
+[configuration]
+title = "SQL"
+suggests = []
+description = "SQLFluff checks layout and style in the project dialect. At all, SQL checks line comments, file length, and PostgreSQL function structure."
+
+[files]
+extensions = [".sql", ".pgsql", ".psql"]
+
+[[tool]]
+name = "sqlfluff"
+crash_pattern = '^Traceback \(most recent call last\):$'
+suppression = { marker = "\\bnoqa\\b", reason = "--[^\\n]*?-- ?(?<reason>\\S.*)" }
+version = "4.3.0"
+min_version = "3.0.0"
+pypi = "sqlfluff"
+mise = "pipx:sqlfluff"
+brew = "sqlfluff"
+[[tool.replace]]
+file = ".sqlfluff"
+shared = false
+
+[[tool.replace]]
+file = ".sqlfluffignore"
+shared = false
+
+[[tool.replace]]
+file = "pyproject.toml"
+table = "tool.sqlfluff"
+shared = true
+
+[[tool.replace]]
+file = "setup.cfg"
+table = "sqlfluff"
+shared = true
+
+[[tool.replace]]
+file = "tox.ini"
+table = "sqlfluff"
+shared = true
+
+[[tool_file]]
+target = ".gspot/config/sqlfluff.cfg"
+tool = "sqlfluff"
+per_scope = true
+rule_keys = ["sqlfluff.exclude_rules", "sqlfluff:rules"]
+
+[[check]]
+name = "sqlfluff"
+example = "The query `select id from user_accounts;` reports CP01 under the configured uppercase keyword policy. Format it as `SELECT id FROM user_accounts;` and rerun using the project dialect."
+level = "recommended"
+stage = "commit"
+command = ["sqlfluff", "lint", "--config", "{tool_file:sqlfluff}", "--ignore-local-config", "--disable-progress-bar", "--format", "json", "{files}"]
+exit_codes = [1]
+fix = ["sqlfluff", "fix", "--config", "{tool_file:sqlfluff}", "--ignore-local-config", "--disable-progress-bar", "{files}"]
+output = { format = "json", children = "violations", fields = { file = "filepath", line = "start_line_no", column = "start_line_pos", rule = "code", message = "description" } }
+summary = "Lints every SQL file for layout, capitalization, aliasing, and ambiguous references, in the dialect the database configuration names."
+why = "SQL that reads one way in every file lets a reviewer look at what the statement does."
+help = "Run gspot check --fix. Turn one rule off with gspot ignore sql/sqlfluff --rule `<code>` --reason \"`<why>`\"."
+
+[[check]]
+name = "functions"
+example = "A SQL function that only forwards one expression reports a trivial-function finding. Inline unnecessary calls and delete the function. If an external API requires the signature, record that with `gspot ignore` and a reason."
+level = "all"
+stage = "commit"
+summary = "For the postgres dialect, reports trivial SQL and PL/pgSQL functions and excessive declared input parameters."
+why = "Unnecessary functions add indirection; excessive parameters obscure responsibilities."
+help = "Inline unnecessary functions. If a required API needs one, run `gspot ignore sql/functions --paths <file> --reason <why>`. Reduce parameters or configure limits.sql.function_parameters."

package/configurations/language/sql/rules/NAMING.md

@@ -0,0 +1,90 @@
+# SQL Naming
+
+SQL names define durable infrastructure interfaces. Rename them only
+through migrations and contract-aware code changes.
+
+## SQL case rules
+
+<!-- level: all -->
+
+- SQL schemas, tables, columns, functions, function parameters, indexes,
+  triggers, constraints, and policies use `lower_snake_case`.
+- Fully qualify grants and function signatures when names have more than one possible meaning.
+- Do not use quoted sentence-style identifiers for local policy names.
+- Do not use pluralization or prefixes inconsistently inside one schema.
+
+| Avoid                        | Prefer                           | Meaning                            |
+| ---------------------------- | -------------------------------- | ---------------------------------- |
+| `public.OrderItems`          | `public.order_items`             | An order-item table.               |
+| `users_can_view_order_items` | `users_can_view_own_order_items` | A policy restricted to owned rows. |
+
+The policy name must describe its actual predicate. A name that says "own"
+does not establish ownership checks or enable Row Level Security.
+
+## Migration filenames
+
+<!-- level: all -->
+
+Follow the migration tool's file names. Name each migration for its durable database change.
+
+## SQL tables and columns
+
+<!-- level: all -->
+
+- Table names identify the domain set stored by the relation.
+- Column names identify the value, not the application layer that reads it.
+- Foreign-key columns use the referenced concept plus `_id`.
+- Timestamp columns use stable event names such as `created_at`,
+  `updated_at`, `deleted_at`, or a concrete domain event time.
+- Boolean columns use concise positive assertion names without an `is_`
+  prefix.
+- Avoid generic columns that hide meaning.
+
+| Avoid     | Prefer                      | Meaning                   |
+| --------- | --------------------------- | ------------------------- |
+| `data`    | `message_delivery_attempts` | Delivery attempt table.   |
+| `payload` | `provider_response`         | Response payload column.  |
+| `flag`    | `retryable`                 | Retry eligibility column. |
+| `date`    | `attempted_at`              | Attempt timestamp column. |
+
+## SQL functions and parameters
+
+<!-- level: all -->
+
+- SQL function names use verb phrases or domain operation names. These verbs govern function
+  names, not migration filenames.
+
+- Retrieval functions use `get_` regardless of whether they return one row,
+  an optional row, a collection, or a paginated collection. Do not use
+  `read_`, `find_`, `fetch_`, `load_`, or `list_` as retrieval synonyms.
+- Data-access mutation functions use `set_`, `insert_`, `update_`, or
+  `delete_` according to the operation they perform. Do not use `create_`,
+  `add_`, `save_`, `write_`, `put_`, `upsert_`, or `remove_` as synonyms.
+- Function parameters use `lower_snake_case`.
+- Parameter names never collide with table column names.
+- `SECURITY DEFINER` functions must have names that make the privileged action
+  clear.
+- Do not name functions like arbitrary script tasks.
+
+Use `archive_expired_orders` for a transactional operation that archives
+expired orders. Name its user argument `target_user_id` when `user_id` already names
+already a column in the affected tables. A generic `run` name hides the
+operation, and an unqualified `id` can obscure column ownership.
+
+## Indexes, constraints, triggers, and policies
+
+<!-- level: all -->
+
+- Name constraints and scope them to their table or concept.
+- Name indexes by table plus indexed columns or purpose.
+- Name triggers by event and action.
+- Name policies by actor plus allowed action.
+- Keep names stable because they appear in migrations, errors, grants, and
+  database inspection output.
+
+| Avoid           | Prefer                            | Meaning                              |
+| --------------- | --------------------------------- | ------------------------------------ |
+| `idx1`          | `messages_user_id_created_at_idx` | Index on user and creation time.     |
+| `check_status`  | `messages_status_not_empty_check` | Nonempty status constraint.          |
+| `trigger1`      | `messages_set_updated_at`         | Update timestamp trigger.            |
+| `select_policy` | `users_can_view_own_messages`     | Policy restricted to owned messages. |

package/configurations/language/sql/rules/SQL.md

@@ -0,0 +1,9 @@
+# SQL
+
+## SQL style
+
+- Fully qualify cross-schema references.
+- Prefer explicit column lists for every `INSERT` and every grant of write
+  privileges.
+- Keep table constraints close to the table definition unless the migration must add them
+  later for dependency reasons.

package/configurations/language/swift/manifest.toml

@@ -0,0 +1,164 @@
+allowed_words = ["Swift", "SwiftLint", "SwiftFormat", "Periphery"]
+
+ignored_folders = [".build", "DerivedData", "Pods"]
+
+[configuration]
+title = "Swift"
+suggests = []
+description = "Swift sources: SwiftLint with stable rules selected by level and analyzer rules, SwiftFormat, a build, and Periphery for dead code."
+
+[detect]
+extensions = [".swift"]
+project_files = ["Package.swift"]
+
+[files]
+extensions = [".swift"]
+filenames = ["Package.swift", "Package.resolved"]
+
+[[tool]]
+name = "swiftlint"
+rule_url = "https://realm.github.io/SwiftLint/{rule}.html"
+suppression = { marker = "\\bswiftlint:disable\\b", reason = " - (?<reason>\\S.*)" }
+builds = ["macos", "linux"]
+version = "0.63.2"
+min_version = "0.57.0"
+mise = "swiftlint"
+brew = "swiftlint"
+github = { name = "realm/SwiftLint", version = "0.63.2" }
+version_command = ["version"]
+[[tool.replace]]
+file = ".swiftlint.yml"
+shared = false
+
+[[tool.replace]]
+file = ".swiftlint.yaml"
+shared = false
+
+[[tool]]
+name = "swiftformat"
+suppression = { marker = "\\bswiftformat:disable\\b", reason = " - (?<reason>\\S.*)" }
+builds = ["macos", "linux"]
+version = "0.61.1"
+min_version = "0.54.0"
+# The GitHub release ships an app bundle beside the executable, which mise skips.
+mise = { name = "swiftformat", version = "0.61.1", options = { no_app = true, rename_exe = "swiftformat" } }
+brew = "swiftformat"
+github = { name = "nicklockwood/SwiftFormat", version = "0.61.1" }
+[[tool.replace]]
+file = ".swiftformat"
+shared = false
+
+[[tool]]
+name = "periphery"
+suppression = { marker = "\\bperiphery:ignore\\b", reason = " - (?<reason>\\S.*)" }
+builds = ["macos"]
+version = "3.6.0"
+min_version = "3.0.0"
+mise = "periphery"
+brew = "periphery"
+github = { name = "peripheryapp/periphery", version = "3.6.0" }
+version_command = ["version"]
+[[tool.replace]]
+file = ".periphery.yml"
+shared = false
+
+[[tool.replace]]
+file = ".periphery.yaml"
+shared = false
+
+[[tool]]
+name = "swift"
+system = true
+
+[[tool]]
+name = "xcodebuild"
+install_hint = "install Xcode from the App Store"
+system = true
+
+[[tool_file]]
+target = ".gspot/config/swiftlint.yml"
+tool = "swiftlint"
+rule_keys = ["opt_in_rules", "analyzer_rules", "disabled_rules"]
+per_scope = true
+pointer = { path = ".swiftlint.yml", body = "parent_config: {target_json}\n" }
+
+[[tool_file]]
+target = ".gspot/config/swiftformat"
+tool = "swiftformat"
+rule_keys = ["enable", "disable"]
+per_scope = true
+
+[[tool_file]]
+target = ".gspot/config/periphery.yml"
+tool = "periphery"
+per_scope = true
+
+[[check]]
+name = "swiftlint"
+example = "The forced cast `value as! NSString` reports `force_cast`. Use a conditional cast and handle the failed conversion, or change the input contract so no cast is required."
+level = "recommended"
+stage = "commit"
+tool = "swiftlint"
+command = ["swiftlint", "lint", "--strict", "--quiet", "--no-cache", "--reporter", "json", "{files}"]
+fix = ["swiftlint", "lint", "--fix", "--quiet", "--no-cache", "{files}"]
+cwd = "scope"
+files = { extensions = [".swift"] }
+output = { format = "json", fields = { file = "file", line = "line", column = "character", rule = "rule_id", message = "reason" } }
+summary = "Lints Swift files with the scoped and nested SwiftLint configurations, treating warnings as errors."
+why = "Forced casts and tries can crash, and a strong delegate can retain its owner. Find these before committing."
+help = "Run gspot check --fix for the rules that fix themselves. Turn one rule off with gspot ignore swift/swiftlint --rule `<id>` --reason \"`<why>`\"."
+
+[[check]]
+name = "swiftformat"
+example = "A declaration beginning `func   greeting` reports `consecutiveSpaces`. Run the configured formatter to obtain `func greeting`, inspect the diff, and rerun."
+level = "recommended"
+stage = "commit"
+command = ["swiftformat", "--lint", "--config", "{tool_file:swiftformat}", "{files}"]
+exit_codes = [1]
+fix = ["swiftformat", "--quiet", "--config", "{tool_file:swiftformat}", "{files}"]
+files = { extensions = [".swift"] }
+output = { format = "regex", pattern = "^(?<file>.+?):(?<line>\\d+):(?<column>\\d+): (?:error|warning): \\((?<rule>\\w+)\\) (?<message>.*)$" }
+summary = "Checks the layout of every Swift file against the shipped SwiftFormat rules."
+why = "One layout everywhere keeps a diff about the change and not about where a brace went."
+help = "Run gspot check --fix."
+
+[[check]]
+name = "build"
+example = "A Swift assignment of a string to an `Int` variable fails compilation. Correct the value or declared type and rerun with the required compiler and project settings available."
+level = "recommended"
+stage = "push"
+runs = "scope"
+needs = ["build"]
+operating_systems = ["macos", "linux"]
+summary = "Builds the package or Xcode scheme incrementally to report compiler errors."
+why = "Swift has no type check without a build, so the build is the type check."
+help = "Fix the first compiler error; later ones are often the same mistake."
+
+[[check]]
+name = "swiftlint-analyze"
+example = "An import unused by the compiled Swift sources reports an analyzer finding. Remove the import and rerun the build-backed analysis. A missing build log does not establish a clean result."
+level = "recommended"
+stage = "manual"
+runs = "scope"
+needs = ["build"]
+operating_systems = ["macos"]
+tool = "swiftlint"
+summary = "Runs the SwiftLint analyzer rules over the compiler log of the build: unused imports and captured variables."
+why = "These rules need the compiler's view of the code, which a file-by-file lint does not have."
+help = "Remove what the rule names. Keep an import the analyzer misjudges under tools.swiftlint.always_keep_imports."
+
+[[check]]
+name = "periphery"
+example = "A declaration with no references in the selected compiled project reports unused code. Delete the unused declaration and rebuild before rerunning. Runtime-only references require a specific documented exception."
+level = "recommended"
+stage = "push"
+runs = "scope"
+needs = ["build"]
+tool = "periphery"
+summary = "Scans the built project for declarations nothing uses."
+why = "Dead code is read, maintained, and migrated by people who cannot tell it is dead."
+help = "Delete the declaration, or mark it with a periphery:ignore comment that says who uses it."
+
+[rules]
+"SWIFTUI.md" = { tags = ["swift-import:SwiftUI"] }
+"UIKIT.md" = { tags = ["swift-import:UIKit"] }

package/configurations/language/swift/rules/NAMING.md

@@ -0,0 +1,88 @@
+# Swift Naming
+
+Swift naming follows the Apple API Design Guidelines and optimizes for call-site clarity.
+
+## Case, scope, and files
+
+<!-- level: all -->
+
+Preserve external names and domain notation that the team uses. Express privacy through access
+modifiers, not an underscore.
+
+Express a structural relationship through nesting rather than a longer
+top-level name: `Parser.Error`, not `ParseError`. A static property does not repeat its
+declaring type: `UIColor.primary`, not `UIColor.primaryColor`. Use `shared` and `default`
+only when they describe the role. Use an empty enum as a namespace only for tightly related
+constants or functions never instantiated.
+
+## Roles
+
+<!-- level: all -->
+
+A suffix says what a type owns and means one thing across the whole codebase. If `Repository`
+owns domain-facing data access in one feature, it does not own HTTP mechanics in another.
+Which suffixes a project uses depends on the pattern it picked, but these framework words have
+one meaning:
+
+| Role word        | Use when                                                                               |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| `View`           | SwiftUI view or UIKit view type that presents UI.                                      |
+| `ViewController` | UIKit screen controller.                                                               |
+| `ViewModel`      | Presentation state and user intent owner for one screen, flow, or cohesive surface.    |
+| `ViewState`      | Value describing screen presentation state.                                            |
+| `ViewAction`     | Typed user or lifecycle intent emitted by a view.                                      |
+| `Coordinator`    | Navigation or flow state owner.                                                        |
+| `Router`         | Route mutation or destination-selection boundary, narrower than a coordinator.         |
+| `DataSource`     | UIKit list adapter that feeds rows and sections.                                       |
+| `CellModel`      | Values a reusable cell renders: strings, image references, state, and lightweight IDs. |
+
+Repository protocols speak domain language and return domain results through domain
+operations such as `TemplateRepository.getTemplate`; an implementation may name its technology
+such as `HTTPTemplateRepository` when that distinguishes real implementations. Client types own
+external API or SDK mechanics such as `TemplateAPIClient`. Coordinators own route state, destination
+construction, stack mutations, and presentation flow such as `TemplateCoordinator.showEditTemplate`.
+Keep route enums within their feature and name them for the flow. Give them stable domain identifiers
+such as `TemplateDestination.editTemplate`. Never give them view models, views, repository implementations, SDK
+clients, database records, or DTOs.
+
+## Methods, labels, and delegates
+
+<!-- level: all -->
+
+When the project uses view models, name a direct UI event for the event
+such as `submitButtonTapped()`, `cameraPermissionDenied()`, `selectedItemChanged(to:)`. Name domain work
+with a domain verb such as `enqueueFileUpload(_:)`, `refreshOrderHistory(for:)`,
+`validateEmailAddress(_:)`; `handle`, `process`, and `didTap` name neither. Reserve `handle...` for
+reserved for literal UIKit target-action and notification handlers marked `@objc`.
+
+Names form grammatical English at the call site: omit the first label when the base
+name and argument form a phrase and included when it clarifies a weak type. Initializer
+arguments that set stored properties use the property names with explicit `self.`, and
+factories use `make...` such as `makeTemplateView(for:)`. Nonmutating methods without side effects
+read as noun phrases, and mutating methods read as imperatives. Pairs follow `sort`/`sorted`,
+`append`/`appending`, `formUnion`/`union`.
+
+A delegate method passes the source object first and unlabeled, and never trims its signature because
+one caller currently owns it. Name a source-only `Void` event with the source type plus a tense
+phrase: `draftStore(_:didDeleteDraft:)`. A source-only `Bool` answer uses `can`, `is`, or
+another predicate, never `should` or `may`: `draftStoreCanDeleteDraft`. Name a source-only value with a
+noun phrase with a natural preposition: `numberOfSections(in:)`. Extra arguments make the
+second label describe the event or requested value:
+`messageListDataSource(_:heightForMessageAt:)`.
+
+## Protocols and identifiers
+
+<!-- level: all -->
+
+A protocol carries no `I` prefix and no `Protocol` suffix. Name a domain role with a noun such as `TemplateRepository`. Name a capability for its behavior, often with `-ing`,
+such as `ProgressReporting`, `ThemeColorProviding`, or `LoginCoordinating`. Avoid an automatic `-able`
+name that describes no clear capability. `Provider`, `Repository`, `Client`, and
+`Coordinating` appear only when the protocol serves that role, and no protocol exists per ViewModel or use
+case merely to enable mocks.
+
+Presentation identifiers provide stable interfaces for UI identity, diffable data sources,
+navigation, persistence, and tests, named for what they identify rather than the framework
+that consumes them. Snapshot items use stable presentation or domain IDs, never DTO identity,
+array offsets, or index paths. `id` suffices when the enclosing type supplies the context
+such as `MessageRow.id`; a role-qualified name such as `selectedMessageID` or `conversationID`
+serves a scope with several identifiers.

package/configurations/language/swift/rules/SWIFT.md

@@ -0,0 +1,134 @@
+# Swift
+
+Swift source follows the Apple API Design Guidelines and the local formatting and lint
+configuration. SwiftFormat owns layout. Treat warnings as errors in the build settings.
+
+## Files and style
+
+Every file imports exactly the top-level modules it uses, as whole modules unless a single
+declaration avoids a known conflict. Group imports by compiler condition, with
+`@testable import` after regular imports in tests. `// MARK: - Section` marks meaningful groups in larger files,
+and a file comment appears only when the file groups several abstractions and the grouping
+needs explanation. Type inference covers a right-hand side with a clear type; an explicit annotation
+covers empty collections, `nil` initial values, weak type information, and public API
+clarity. Enum raw values that map to an external wire or persistence contract need documentation;
+an explicit case list replaces `default` where a future case must force review. Attributes
+with parameters go on their own line when they hurt readability inline.
+
+### File organization
+
+<!-- level: all -->
+
+One primary top-level type per file, with small private helpers allowed beside it. Keep overloads adjacent. Organize extensions rather than scattering them across files. Group SwiftUI
+dynamic properties by property-wrapper type.
+
+Good:
+
+```swift
+private func sumPositive(_ values: [Int]) -> Int {
+    var total = 0
+    for value in values where value > 0 {
+        total += value
+    }
+    return total
+}
+
+/// Compare the sums of positive values in two collections.
+public func comparePositiveTotals(_ left: [Int], _ right: [Int]) -> Int {
+    sumPositive(left) - sumPositive(right)
+}
+```
+
+## Practices
+
+Use `let` by default and `var` for required mutation. Class-constrained protocols use
+`AnyObject`. Prefer shorthand types such as `[Element]`, `[Key: Value]`, or `Wrapped?`, and use `Void` for function
+types. Optionals express valid absence rather than sentinel values, compared to
+`nil` when only presence matters and bound when the code uses the value, chained for one-off access.
+
+Typed errors distinguish several meaningful failure states. A force unwrap or cast needs a
+proven invariant. At level `all`, use `// swiftlint:disable:next force_unwrapping` with the
+invariant as the reason for an unavoidable unwrap. Avoid global mutable state, with `static let` or computed `static var` over stored
+mutable statics.
+
+`guard` handles early exits, `for ... where` a loop guarded by one condition,
+`for` over `forEach` for control flow or async work, and `map`, `compactMap`, and
+`filter` express side-effect-free transformation. Pattern bindings put `let` on each element
+where that avoids ambiguity. Use weak capture only when a callback must not extend the captured
+object's lifetime. Otherwise, capture the immutable values the callback needs. `#fileID` serves production diagnostics; `#filePath`
+only tests and tooling. Overload operators only with their standard meaning, and a
+custom operator exists only as standard domain notation.
+
+### API and ownership conventions
+
+<!-- level: all -->
+
+Structs keep synthesized
+memberwise initializers where sufficient, value types hold data without identity, and classes
+serve identity, reference semantics, lifecycle, observable state, or framework requirements.
+An implicitly unwrapped optional appears only for Apple lifecycle cases such as `@IBOutlet`,
+Objective-C nullability gaps, and test data.
+
+Declare top-level access to match the public contract. An extension carries no blanket access
+modifier. Types nest when they only make sense in the parent's context, and a caseless enum
+groups truly related statics. Methods and properties beat free functions unless the function
+follows the standard library and stays symmetric.
+Logging goes through the project logging system, and
+images and colors come from named assets or explicit constructors.
+
+## Networking
+
+URLs come from `URLComponents` or a typed endpoint value, never concatenated query strings,
+and a production `URL(string:)!` documents its invariant. Inject base URLs and credentials
+at composition. Use `Encodable` types for request bodies with an explicit method and
+content type, never `[String: Any]`. `URLSession` succeeds for non-2xx responses.
+Validate `HTTPURLResponse` status explicitly. Treat a non-HTTP response as a transport
+failure.
+
+Responses decode into DTOs mapped into domain values at the boundary. Validate required fields and
+external enum values there. Do not invent a fallback ID, date, or case.
+Clients expose typed errors distinguishing encoding, decoding, transport, invalid response,
+invalid status, and cancellation, which stays distinguishable when navigation supersedes a
+task. When you write tests, inject the transport and cover request construction, status validation,
+decoding failure, cancellation, and mapping without a live service.
+
+### Networking ownership
+
+<!-- level: all -->
+
+A network client owns base URL, path construction, query items, method, headers, body
+encoding, transport calls, status validation, and decoding. Views and view models never build
+a `URLRequest`, call `URLSession`, decode a DTO, or inspect a status. Prefer Foundation `URLSession`
+with async/await rather than a third-party networking framework.
+
+## Documentation comments
+
+`///` documents a declaration before its attributes and modifiers. Swift markup uses
+`- Parameter name:`, `- Parameters:`, `- Returns`, and `- Throws`. Backticks name parameters
+and types. `// MARK:`, implementation notes, and tool directives use ordinary `//` comments.
+
+## Concurrency and errors
+
+Structured `async`/`await` with `async throws` APIs replaces callback pyramids and unmanaged
+task trees. UI state mutates on the main actor. When the project uses view models, keep them
+`@MainActor`.
+
+Expensive work moves into use cases, repositories, actors, or background tasks. `Task` creation stays
+in the modules that need them: view models, coordinators, or views through `.task`, never in an initializer, always
+with an owner and a cancellation strategy. Store handles when a disappearing view, a
+retry, or a newer request must cancel older work. Check cancellation in long loops and
+before publishing stale results.
+
+Shared mutable state sits behind actors, main-actor
+isolation, or explicit synchronization, with actor isolation preferred over
+`DispatchQueue.main.async`. The compiler verifies `Sendable` designs; a module without
+concurrency annotations gets `@preconcurrency import`, and `@unchecked Sendable` or
+`nonisolated(unsafe)` appears only with a documented local invariant and no safer design.
+Inject clocks and scheduling interfaces where time affects logic or tests.
+
+Typed errors serve callers with different recovery paths, and untyped `Error` only generic
+boundaries where cases add nothing. Technical errors become user-facing messages at the presentation
+boundary. Failed operations throw, and UI loading and error display use explicit state enums.
+Reserve `fatalError` for an unrecoverable programmer error with a documented invariant,
+`assertionFailure` for an unexpected but recoverable state, and `precondition` for an invariant
+that continuing requires.

package/configurations/language/swift/rules/SWIFTUI.md

@@ -0,0 +1,61 @@
+# SwiftUI
+
+## Architecture
+
+<!-- level: all -->
+
+This rule picks no presentation pattern, such as Model-View-ViewModel (MVVM) or The Composable Architecture (TCA); a project that wants one writes it
+down.
+
+## SwiftUI views
+
+- Keep view-local state in the view when its lifetime matches the view's identity.
+  Use `@State`, `@FocusState`, `@GestureState`, and bindings according to their
+  ownership and read contracts.
+- Keep view-owned state properties private. Inject values owned by a parent
+  through the appropriate input or binding.
+- Preserve read and actor isolation when state changes.
+- Do not store derived state in `@State` when source state provides enough data to compute it.
+- Avoid heavy computation in `body`; SwiftUI can evaluate it repeatedly.
+- Preserve cancellation and stale-result handling for lifecycle work started with
+  `.task`, `.onAppear`, or refresh actions.
+
+### View organization
+
+<!-- level: all -->
+
+- Views render state and forward user intent to the project's operation or state owner.
+- Keep business workflows, network calls, database calls, and concrete infrastructure
+  construction in their existing owners.
+- Do not add explicit `@ViewBuilder` to `body`; the compiler provides it.
+- Use `@ViewBuilder` for helper properties or functions that need conditional view branches.
+- Omit `else { EmptyView() }` when the missing branch already produces no content.
+- Extract subviews by visual responsibility, not to reduce line count.
+- Give reusable views explicit inputs instead of hidden dependencies on broad environment objects.
+- Keep short display formatting local. Put reusable or domain-sensitive formatting
+  with the behavior that owns it.
+
+## State ownership
+
+<!-- level: all -->
+
+Keep screen and flow state in the project's selected state owner. Use a shared owner
+when multiple screens need the same state. A store owns cohesive feature or domain
+state; app-wide state belongs in app composition only for global state, such as
+session, theme, or connectivity.
+
+Prefer an enum for mutually exclusive loading states instead of parallel booleans.
+Keep transient UI state out of the domain model.
+
+## Shared state correctness
+
+Use a single source of truth or an explicit refresh strategy when multiple views
+consume the same domain state. Do not assume that creating a second observable
+object keeps it synchronized with the first. Preserve the intended object's lifetime
+across view reconstruction and identity changes.
+
+## Accessibility
+
+- Interactive controls get traits, states, and hints when the visible label does not provide enough information.
+- `.accessibilityHidden(true)` hides only decorative or duplicate content.
+- Ask the user to check navigation, modal presentation, focus, and custom controls with VoiceOver.