Subskill: Swift Architecture, Coding Standards, Testing & Verification
Activation Criteria
Activate this subskill when:
- Developing, refactoring, or reviewing any Swift code under
swift/orPackage.swift. - Implementing state logic, JSON pointer evaluation, or SwiftUI component views.
- Writing or modifying Swift unit tests.
1. Swift Target Architecture
The Swift implementation uses targets defined in root Package.swift:
A2UIJSON(core/Sources/A2UIJSON): Pure JSON Schema 2020-12 definitions and remote schema registry storage.A2UICore(core/Sources/A2UICore): Stateful runtime engine managingMessageProcessor,DataModel,SurfaceGroupModel, pointer evaluation, and action routing.BasicCatalog(core/Sources/BasicCatalog): Core schema definitions and function handlers for Basic Catalog components.A2UISwiftUI(swiftui/Sources/A2UISwiftUI): SwiftUI adapter providing the rootSurfaceview, recursiveComponentNodeView, and environment keys.BasicCatalogSwiftUI(swiftui/Sources/BasicCatalog): Concrete SwiftUI view implementations conforming toComponentImplementation.A2UISampleClient(swift/sample): Interactive iOS Gallery application managed via Xcode project file.
2. Mandatory Coding Standards
All Swift code must strictly follow swift/CODING_STANDARDS.md and the Google Swift Style Guide:
- One primary type per file: Every class, struct, enum, and protocol must live in a dedicated file named after the type.
- 100-character line limit: No line of code, comment, docstring, or markdown may exceed 100 characters.
- 2-space indentation: Enforced by
swift-format. - Apache 2.0 copyright header: Required on every new
.swiftfile:// Copyright 2024 Google LLC // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // https://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. - Safe optional handling: Never use force-unwrapping (
!) or forced tries (try!) on runtime or external data; use optional bindings (if let,guard let) or propagate throwing errors. Usingtry!or!is permitted for hardcoded compile-time constants (e.g., static regular expressions or embedded JSON Schema literals) that can only fail due to a developer error in transcribing the static string.
3. Swift Testing Conventions
Tests use the native Swift Testing framework:
- Import
Testinginstead ofXCTest. - Annotate test functions with
@Test. - Use
#expect(...)for assertions. - In tests, replace force unwraps with
try #require(...)to produce clean test failures instead of crashes. - Avoid
@testable import. Test only the public API surface. - Use standard camelCase identifiers for test function names without backticks or spaces.
4. Verification Workflow
After making any code changes in swift/, run this verification sequence from the repository root:
- Auto-format code:
swift-format format -i -r Package.swift swift/ - Lint check:
swift-format lint -r Package.swift swift/ - Run unit tests:
Or run filtered tests during iterative development:swift testswift test --filter A2UICoreTests swift test --filter A2UISwiftUITests - Compile check:
swift build
5. Integration with Repository Skills
- Blueprint compliance: When updating models or schemas, check compliance with
a2ui-blueprint-compliance. - Test quality: Verify assertion strength and boundary cases with
a2ui-test-quality-check. - Documentation sync: Ensure documentation reflects code changes using
a2ui-doc-sync-check. - Changelog updates: When changing
publicAPIs or consumer-observable behavior in published Swift library products, updateswift/CHANGELOG.mdusingupdate-changelog.