@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/swift-api-design-guidelines/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "swift-api-design-guidelines",
+  "evals": [
+    {
+      "id": 0,
+      "name": "api-review-naming-labels",
+      "prompt": "Review this proposed Swift API surface for a shared design system module and suggest corrected names, argument labels, and call sites. Keep the answer concise and explain the Swift API Design Guidelines rule behind each change.\n\n```swift\npublic struct ThemePalette {\n    public mutating func add(color: UIColor)\n    public mutating func remove(index: Int) -> UIColor\n    public func colorWithName(_ string: String) -> UIColor?\n    public func containsColor(_ color: UIColor) -> Bool\n    public static func createDefaultPalette() -> ThemePalette\n}\n\nlet palette = ThemePalette.createDefaultPalette()\npalette.colorWithName(\"warning\")\n```",
+      "expected_output": "A concise API design review that corrects labels and names using Swift API Design Guidelines: grammatical first-argument omission, role-based names, needed prepositions, needless-word removal, Boolean assertion naming, and make-prefix factory naming.",
+      "files": [],
+      "expectations": [
+        "Recommends `add(_ color:)` or an equivalent fluent `add(_:)` form for adding a color instead of `add(color:)`.",
+        "Recommends a prepositional label such as `remove(at:)` for position-based removal.",
+        "Replaces weak names such as `_ string` with a role-based label/name such as `named name` or `forName name`.",
+        "Removes needless type repetition from names such as `containsColor` when the argument type already conveys color.",
+        "Uses the `make` prefix for a factory method instead of `createDefaultPalette`.",
+        "Explains changes in terms of call-site clarity and Swift API Design Guidelines rather than generic style preference."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "mutating-pairs-doc-comments",
+      "prompt": "I am designing a public Swift `TextBuffer` API. Please propose corrected mutating/nonmutating pair names and documentation comments for these operations: sort lines in-place vs return sorted lines, strip all newline characters in-place vs return a copy with newlines stripped, and union the buffer's tag set in-place vs return a combined tag set. Include any needed complexity notes for non-O(1) computed properties.\n\nCurrent draft:\n\n```swift\npublic struct TextBuffer {\n    public var totalCharacterCount: Int { lines.reduce(0) { $0 + $1.count } }\n    public mutating func formSortLines()\n    public func sortLines() -> TextBuffer\n    public mutating func stripNewlines()\n    public func strippedNewlines() -> TextBuffer\n    public mutating func unionTags(_ tags: Set<String>)\n    public func formUnionTags(_ tags: Set<String>) -> Set<String>\n}\n```",
+      "expected_output": "Corrected API names and documentation comments that apply side-effect naming, -ed/-ing direct-object guidance, form-prefix noun-operation guidance, and non-O(1) computed-property complexity documentation.",
+      "files": [],
+      "expectations": [
+        "Uses imperative mutating names and participle nonmutating names for verb-described operations, such as `sortLines()` / `sortedLines()`.",
+        "Uses `strippingNewlines()` rather than `strippedNewlines()` for the nonmutating direct-object operation.",
+        "Uses noun/form-noun pairing for set-like union, with nonmutating `union...` and mutating `formUnion...` naming.",
+        "Adds documentation comment summaries that describe what methods do and return, and what properties are.",
+        "Documents the complexity of `totalCharacterCount` because it is a non-O(1) computed property.",
+        "Does not present `formSortLines()` or `formUnionTags()` returning a value as the corrected design."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "sibling-boundary-language-features",
+      "prompt": "I need help with three Swift cleanup items in a package: choose better public API names and argument labels for `func fetchDataWithId(_ id: String)`, decide whether to use `some` or `any` for a protocol return type, and configure SwiftLint to enforce identifier naming. Which parts should the Swift API Design Guidelines skill own, and which should be routed elsewhere? Give a short routing answer with minimal concrete examples.",
+      "expected_output": "A boundary-aware answer that uses swift-api-design-guidelines for naming and argument labels, routes language feature details to swift-language, routes lint configuration to swiftlint, and avoids expanding this skill into those sibling domains.",
+      "files": [],
+      "expectations": [
+        "Says swift-api-design-guidelines owns public API naming, role-based names, and argument-label/call-site clarity for `fetchDataWithId(_:)`.",
+        "Gives a minimal API-design example such as `fetchData(id:)` or a more domain-specific role name without over-implementing the whole API.",
+        "Routes `some` vs `any` protocol type-system guidance to the swift-language skill or domain.",
+        "Routes SwiftLint configuration and identifier-name enforcement to the swiftlint skill or domain.",
+        "Does not provide a full SwiftLint configuration or a full opaque/existential type tutorial.",
+        "Preserves sibling-skill boundaries while giving enough API-design guidance to be useful."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/swift-api-design-guidelines/references/argument-labels-and-parameters.md

@@ -0,0 +1,164 @@
+# Argument Labels and Parameters
+
+Extended examples for argument label rules, edge cases, parameter naming, and default argument strategy.
+
+## Contents
+
+- [Prepositional Phrase Rule Edge Cases](#prepositional-phrase-rule-edge-cases)
+- [Grammatical Phrase Rule Extended Examples](#grammatical-phrase-rule-extended-examples)
+- [Value-Preserving vs Narrowing Conversions](#value-preserving-vs-narrowing-conversions)
+- [Parameter Naming for Documentation](#parameter-naming-for-documentation)
+- [Default Arguments Over Method Families](#default-arguments-over-method-families)
+
+## Prepositional Phrase Rule Edge Cases
+
+The base rule: when the first argument completes a prepositional phrase with the base name, use the preposition as the argument label.
+
+```swift
+// Standard cases  -  preposition is the label
+x.removeBoxes(havingLength: 12)
+view.fade(from: red)
+path.relativePath(from: root)
+```
+
+### Abstraction boundary exception
+
+When the first two arguments represent parts of a single abstraction, fold the preposition into the base name so each component gets its own label.
+
+```swift
+// GOOD  -  x and y are parts of a single abstraction (a point)
+a.moveTo(x: b, y: c)
+
+// BAD  -  forces x and y into a single prepositional phrase
+a.move(toX: b, y: c)
+```
+
+```swift
+// GOOD  -  row and column are parts of a single abstraction (a cell position)
+table.cellAt(row: r, column: c)
+
+// BAD
+table.cell(atRow: r, column: c)
+```
+
+### Multiple prepositional phrases
+
+When a method involves multiple prepositions, each argument gets its own prepositional label.
+
+```swift
+// GOOD
+database.move(item, from: source, to: destination)
+
+// GOOD
+view.transition(from: oldState, to: newState, duration: 0.3)
+```
+
+## Grammatical Phrase Rule Extended Examples
+
+When the first argument and base name form a grammatical phrase, omit the first label and absorb any leading words into the base name.
+
+```swift
+// GOOD  -  "add subview"
+view.addSubview(child)
+
+// GOOD  -  "contains element"
+array.contains(element)
+```
+
+### Absorbing leading words
+
+If the label would start with words that belong in the base name, move them.
+
+```swift
+// GOOD  -  "having length" absorbed into base name
+removeBoxes(havingLength: 12)
+
+// BAD  -  should be part of the base name
+remove(boxesHavingLength: 12)
+```
+
+## Value-Preserving vs Narrowing Conversions
+
+**Value-preserving (widening)**  -  the conversion cannot lose information. Omit the first label.
+
+```swift
+Int64(someUInt32)           // UInt32 always fits in Int64
+String(someCharacter)       // Character is always a valid String
+Double(someFloat)           // Float always fits in Double
+```
+
+**Narrowing or lossy**  -  the conversion may lose information or change representation. Use a descriptive label.
+
+```swift
+Int64(truncating: someDecimal)      // may lose precision
+UInt32(clamping: someLargeInt)      // may clamp to bounds
+String(describing: someObject)      // uses debug representation
+Int(exactly: someDouble)            // may return nil
+```
+
+**Representation change**  -  the conversion changes how the value is viewed. Use a label that describes the interpretation.
+
+```swift
+String(utf8String: cString)         // interprets as UTF-8
+Data(contentsOf: url)               // reads from file
+URL(string: urlString)              // parses string as URL
+```
+
+## Parameter Naming for Documentation
+
+Parameter names drive the clarity of generated documentation, even though they do not appear at most call sites. Choose names that read well in a doc comment.
+
+```swift
+/// Finds the index of the equivalent element.
+///
+/// - Parameter element: The element to search for.
+/// - Returns: The index of `element`, or `nil` if not found.
+func index(of element: Element) -> Int?
+```
+
+Compare with a poorly named parameter:
+
+```swift
+/// Finds the index of the equivalent element.
+///
+/// - Parameter e: ???
+func index(of e: Element) -> Int?
+```
+
+Name parameters as complete English words. Single letters and abbreviations damage documentation quality.
+
+## Default Arguments Over Method Families
+
+Prefer a single method with default parameter values over a family of methods.
+
+```swift
+// GOOD  -  one method, sensible defaults
+func decode(
+    _ data: Data,
+    encoding: String.Encoding = .utf8,
+    allowLossyConversion: Bool = false
+) -> String?
+```
+
+```swift
+// BAD  -  method family that differs only in which parameters are present
+func decode(_ data: Data) -> String?
+func decode(_ data: Data, encoding: String.Encoding) -> String?
+func decode(_ data: Data, encoding: String.Encoding, allowLossyConversion: Bool) -> String?
+```
+
+### Ordering defaulted parameters
+
+Place parameters with defaults at the end. Parameters without defaults typically carry more meaning and form the grammatical base of the call site.
+
+```swift
+// GOOD  -  required parameters first
+func search(
+    query: String,
+    in scope: SearchScope = .all,
+    limit: Int = 50,
+    offset: Int = 0
+) -> [Result]
+```
+
+Exception: when a trailing closure is the most common override, it may come after defaulted parameters.

package/pipeline/skills/shared/external/swift-api-design-guidelines/references/conventions-and-special-rules.md

@@ -0,0 +1,219 @@
+# Conventions and Special Rules
+
+Casing conventions, complexity documentation, free function exceptions, overload safety, and tuple/closure naming.
+
+## Contents
+
+- [Casing Conventions](#casing-conventions)
+- [Complexity Documentation](#complexity-documentation)
+- [Free Function Exceptions](#free-function-exceptions)
+- [Overload Safety](#overload-safety)
+- [Tuple Member and Closure Parameter Naming](#tuple-member-and-closure-parameter-naming)
+- [Unconstrained Polymorphism](#unconstrained-polymorphism)
+
+## Casing Conventions
+
+Types and protocols use `UpperCamelCase`. Everything else  -  functions, methods, properties, variables, constants, enum cases, argument labels  -  uses `lowerCamelCase`.
+
+### Acronym handling
+
+Acronyms that appear as all-uppercase in common American English usage are uniformly upper- or lower-cased based on their position in the name.
+
+```swift
+// At the start of a lowerCamelCase name  -  all lowercase
+var utf8Bytes: [UTF8.CodeUnit]
+var htmlParser: HTMLParser
+var urlSession: URLSession
+
+// In the middle or end  -  follows the case of its position
+var isRepresentableAsASCII = true
+var userSMTPServer: SMTPServer
+
+// Type names  -  acronym stays uppercase
+struct HTTPRequest { ... }
+class URLSessionTask { ... }
+enum UTF8 { ... }
+```
+
+Words that started as acronyms but are now common words follow standard casing:
+
+```swift
+// These are words, not acronyms
+var radarDetector: RadarDetector   // not "RADARDetector"
+var laserPrinter: LaserPrinter     // not "LASERPrinter"
+var scubaGear: ScubaGear           // not "SCUBAGear"
+```
+
+## Complexity Documentation
+
+Callers assume computed properties are O(1). Document the complexity of any computed property or subscript that does more work.
+
+```swift
+/// The total number of nodes in the tree.
+///
+/// - Complexity: O(*n*), where *n* is the number of nodes.
+var nodeCount: Int {
+    root.descendants.count
+}
+```
+
+```swift
+/// The element at the given offset from the start.
+///
+/// - Complexity: O(*k*), where *k* is the offset.
+subscript(offset: Int) -> Element {
+    var current = startIndex
+    for _ in 0..<offset { current = index(after: current) }
+    return self[current]
+}
+```
+
+Properties that are genuinely O(1) do not need a complexity note  -  the default assumption is correct.
+
+```swift
+// O(1)  -  no note needed
+var count: Int { storage.count }
+var isEmpty: Bool { count == 0 }
+var first: Element? { storage.first }
+```
+
+## Free Function Exceptions
+
+Prefer methods and properties to free functions. Use a free function only when one of these three conditions holds:
+
+**1. No obvious `self`**
+
+```swift
+// GOOD  -  neither argument is more "self" than the other
+min(x, y)
+max(a, b)
+zip(sequence1, sequence2)
+```
+
+**2. Unconstrained generic**
+
+```swift
+// GOOD  -  works on anything
+print(value)
+debugPrint(value)
+```
+
+**3. Established domain notation**
+
+```swift
+// GOOD  -  mathematical convention
+sin(x)
+cos(x)
+abs(value)
+```
+
+If none of these apply, make it a method.
+
+```swift
+// BAD  -  has an obvious self
+calculateDistance(from: pointA, to: pointB)
+
+// GOOD
+pointA.distance(to: pointB)
+```
+
+## Overload Safety
+
+Methods may share a base name when they operate in different type domains or when their meaning is clear from context.
+
+```swift
+// GOOD  -  different parameter types, same semantic operation
+extension Collection {
+    func contains(_ element: Element) -> Bool
+    func contains(where predicate: (Element) -> Bool) -> Bool
+}
+```
+
+### Avoid return-type-only overloads
+
+Overloads that differ only in return type create ambiguity when the compiler cannot infer the expected type.
+
+```swift
+// BAD  -  ambiguous at call site
+func transform() -> Int { ... }
+func transform() -> String { ... }
+
+let result = transform()  // error: ambiguous
+```
+
+### Safe overloading patterns
+
+```swift
+// GOOD  -  different first argument labels disambiguate
+func fetch(id: Int) -> User
+func fetch(name: String) -> User
+
+// GOOD  -  different argument types
+func draw(_ rect: CGRect)
+func draw(_ path: CGPath)
+```
+
+## Tuple Member and Closure Parameter Naming
+
+Label tuple members and closure parameters in public API signatures. Positional access (`.0`, `.1`) is fragile and unreadable.
+
+### Tuple members
+
+```swift
+// GOOD  -  labeled
+func position() -> (x: Double, y: Double)
+func range() -> (lower: Int, upper: Int)
+
+let pos = item.position()
+pos.x   // clear
+pos.y   // clear
+
+// BAD  -  unlabeled
+func position() -> (Double, Double)
+
+let pos = item.position()
+pos.0   // what is this?
+pos.1   // what is this?
+```
+
+### Closure parameters
+
+Name closure parameters where they appear in the API, especially for higher-order functions.
+
+```swift
+// GOOD
+func filter(_ isIncluded: (Element) -> Bool) -> [Element]
+func map<T>(_ transform: (Element) -> T) -> [T]
+func sort(by areInIncreasingOrder: (Element, Element) -> Bool)
+
+// BAD
+func filter(_ predicate: (Element) -> Bool) -> [Element]  // acceptable but less descriptive
+func sort(by compare: (Element, Element) -> Bool)          // "compare" is vague
+```
+
+## Unconstrained Polymorphism
+
+Be careful with overloads involving `Any`, `AnyObject`, or unconstrained generics. They can silently match when a more specific overload was intended.
+
+```swift
+// DANGEROUS  -  both overloads match array literals
+struct Container {
+    func append(_ element: Element)
+    func append(_ sequence: some Sequence<Element>)
+}
+
+values.append([2, 3, 4])  // which overload? ambiguous if Element is Array
+```
+
+Resolve with distinct argument labels:
+
+```swift
+// GOOD  -  unambiguous
+struct Container {
+    func append(_ element: Element)
+    func append(contentsOf sequence: some Sequence<Element>)
+}
+
+values.append(singleValue)
+values.append(contentsOf: [2, 3, 4])  // always clear
+```

package/pipeline/skills/shared/external/swift-api-design-guidelines/references/naming-and-clarity.md

@@ -0,0 +1,184 @@
+# Naming and Clarity
+
+Extended examples for name selection, role-based naming, weak-type compensation, and terminology.
+
+## Contents
+
+- [Include Words Needed for Clarity](#include-words-needed-for-clarity)
+- [Omit Needless Words](#omit-needless-words)
+- [Name by Role Not Type](#name-by-role-not-type)
+- [Compensate for Weak Type Information](#compensate-for-weak-type-information)
+- [Terminology Selection](#terminology-selection)
+
+## Include Words Needed for Clarity
+
+If omitting a word makes the call site ambiguous, keep it. The test: can a reader unfamiliar with the declaration understand the call site?
+
+```swift
+// GOOD  -  "for" distinguishes key lookup from index lookup
+dictionary.removeValue(forKey: key)
+
+// BAD  -  is key the value or the lookup key?
+dictionary.remove(key)
+```
+
+```swift
+// GOOD  -  "for" clarifies the relationship
+extension List {
+    func member(for key: Key) -> Value?
+}
+
+// BAD  -  what is "key" relative to the list?
+extension List {
+    func member(_ key: Key) -> Value?
+}
+```
+
+```swift
+// GOOD  -  preposition clarifies direction
+view.fade(from: previousColor)
+
+// BAD  -  is this the target or the source?
+view.fade(previousColor)
+```
+
+## Omit Needless Words
+
+Remove words that merely restate type information. Every word in a name should convey information not already available.
+
+```swift
+// GOOD
+allViews.remove(cancelButton)
+
+// BAD  -  "Element" repeats the type constraint
+allViews.removeElement(cancelButton)
+```
+
+```swift
+// GOOD
+let result = parser.parse(data)
+
+// BAD  -  "Data" is already the parameter type
+let result = parser.parseData(data)
+```
+
+```swift
+// GOOD
+func move(to point: CGPoint)
+
+// BAD  -  "point" is already in the type
+func moveToPoint(_ point: CGPoint)
+```
+
+## Name by Role Not Type
+
+Variables, parameters, and associated types should describe the entity's role in the current context.
+
+```swift
+// GOOD  -  describes the role
+var greeting: String
+var bodyText: String
+let widthConstraint: NSLayoutConstraint
+func restock(from supplier: Warehouse)
+
+// BAD  -  describes the type
+var string: String
+var text: String
+let constraint: NSLayoutConstraint
+func restock(from warehouse: Warehouse)
+```
+
+For associated types in protocols, name by the role in the protocol's semantics:
+
+```swift
+// GOOD
+protocol Container {
+    associatedtype Element
+    associatedtype Index
+}
+
+// BAD  -  names the constraint, not the role
+protocol Container {
+    associatedtype ItemType
+    associatedtype IntegerIndex
+}
+```
+
+## Compensate for Weak Type Information
+
+When a parameter type is `Any`, `AnyObject`, `NSObject`, or a fundamental type (`Int`, `String`, `Double`), the call site may lack enough context to convey meaning. Add clarifying words to the name.
+
+```swift
+// GOOD  -  role words compensate for weak types
+func addObserver(_ observer: NSObject, forKeyPath path: String)
+func fill(with color: UIColor, alpha: Double)
+func setTag(_ tag: Int, for view: UIView)
+
+// BAD  -  weak types make the call site opaque
+func add(_ object: NSObject, for string: String)
+func fill(with any: UIColor, _ value: Double)
+func set(_ value: Int, for object: UIView)
+```
+
+For function return types, the same principle applies:
+
+```swift
+// GOOD  -  return context clarifies weak type
+func maximumScore() -> Int
+func playerName() -> String
+
+// BAD  -  generic return with no context
+func value() -> Int
+func name() -> String
+```
+
+## Terminology Selection
+
+### Prefer common words over obscure terms
+
+Use a common English word when it works. Reserve terms of art for situations where the precise technical meaning matters and no common word captures it.
+
+```swift
+// GOOD  -  common word suffices
+skin                // not "epidermis"
+beginners           // not "neophytes"
+
+// GOOD  -  term of art is precise and necessary
+func sin(_ angle: Double) -> Double  // "sine" is the term of art
+```
+
+### Preserve established meanings
+
+Never use a term of art with a non-standard meaning. Anyone who knows the term expects its conventional definition.
+
+```swift
+// GOOD  -  Array is the established term
+struct Array<Element> { ... }
+
+// BAD  -  "List" means something different in CS (linked list)
+struct List<Element> { ... }  // if it's really an array
+```
+
+### Avoid abbreviations
+
+Do not abbreviate unless the abbreviation is universally understood in the domain. Spell words out.
+
+```swift
+// GOOD
+var backgroundColor: UIColor
+var characterIndex: Int
+
+// BAD
+var bgColor: UIColor
+var charIdx: Int
+```
+
+### Embrace precedent
+
+Follow naming conventions already established in the ecosystem, even if they conflict with a "purer" design.
+
+```swift
+// GOOD  -  matches existing Swift/Cocoa convention
+Array, Dictionary, Set       // not Vector, Map, HashSet
+sin(x), cos(x)              // not sine(x), cosine(x)
+```