@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -4,46 +4,44 @@
     {
       "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.",
+      "prompt": "Please review the naming on this type before we make it public:\n\nstruct ThemePalette {\n    mutating func add(color: Color)\n    mutating func remove(index: Int)\n    func colorWithName(_ string: String) -> Color?\n    func containsColor(_ color: Color) -> Bool\n    static func createDefaultPalette() -> ThemePalette\n}",
+      "expected_output": "Concrete renames grounded in the guidelines: add(_:), remove(at:), a role-named lookup such as color(named name:) or color(forName name:), contains(_:), makeDefault() or similar, each justified by how the call site reads.",
       "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."
+        "Recommends add(_:) because the argument continues the phrase started by the base name",
+        "Recommends remove(at:) so the index is not mistaken for the element",
+        "Replaces the type-named parameter string with a role name, for example color(named name:) or color(forName name:)",
+        "Removes the repeated type word from containsColor, giving contains(_:)",
+        "Replaces the create prefix with a make factory name",
+        "Justifies each change by call-site clarity and the guidelines rather than personal taste"
       ]
     },
     {
       "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.",
+      "prompt": "Fix the names and docs on this editor buffer:\n\nstruct TextBuffer {\n    mutating func formSortLines()\n    func sortLines() -> TextBuffer\n    func strippedNewlines() -> TextBuffer\n    func unionTags(_ other: Set<String>) -> Set<String>\n    mutating func formUnionTags(_ other: Set<String>) -> Set<String>\n    var totalCharacterCount: Int { lines.map(\\.count).reduce(0, +) }\n}",
+      "expected_output": "Verb pair sortLines()/sortedLines(), strippingNewlines(), noun pair unionTags/formUnionTags with the mutating one returning nothing, kind-appropriate doc summaries and an O(n) complexity note on totalCharacterCount.",
       "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."
+        "Names the pair sortLines() for the mutating form and sortedLines() for the non-mutating form",
+        "Uses strippingNewlines() rather than strippedNewlines()",
+        "Pairs the noun operation as unionTags(_:) returning a value and formUnionTags(_:) mutating in place",
+        "Writes doc summaries that match the declaration kind",
+        "Adds a complexity note to totalCharacterCount because it is not O(1)",
+        "Never presents formSortLines() or a value-returning formUnionTags() as correct"
       ]
     },
     {
       "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.",
+      "prompt": "Three quick ones: is fetchDataWithId(_:) a good method name, should our repository return some Collection or any Collection, and how should we configure SwiftLint's identifier_name rule?",
+      "expected_output": "A short naming answer with a corrected example such as fetchData(id:), then routing some versus any to swift-language and the SwiftLint configuration to swiftlint without covering either in depth.",
       "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."
+        "Answers the naming question with a minimal corrected example such as fetchData(id:)",
+        "Routes the some versus any question to swift-language",
+        "Routes the SwiftLint configuration to swiftlint",
+        "Does not give a full SwiftLint configuration or an opaque versus existential type tutorial"
       ]
     }
   ]

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

@@ -1,164 +1,163 @@
 # Argument Labels and Parameters
 
-Extended examples for argument label rules, edge cases, parameter naming, and default argument strategy.
+Harder cases for the label rules in the main skill, plus how to name
+parameters and order defaulted ones.
 
-## Contents
+## Prepositional labels
 
-- [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.
+The base rule: when the first argument finishes a prepositional phrase that
+the base name starts, the preposition is its label.
 
 ```swift
-// Standard cases  -  preposition is the label
-x.removeBoxes(havingLength: 12)
-view.fade(from: red)
-path.relativePath(from: root)
+removeBoxes(havingLength: 12)
+fade(from: red)
+relativePath(from: root)
 ```
 
-### Abstraction boundary exception
+### When two arguments form one idea
 
-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.
+If the first two arguments are coordinates of a single thing, a label like
+`atRow:` would glue the preposition to only one of them. Keep the preposition in
+the base name and label each part:
 
 ```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)
+grid.cellAt(row: r, column: c)        // row and column together locate one cell
+grid.cell(atRow: r, column: c)        // avoid: "at" seems to belong to row only
 ```
 
-```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)
-```
+The same reasoning gives `moveTo(x:y:)` rather than `move(toX:y:)`.
 
-### Multiple prepositional phrases
+### Several prepositions
 
-When a method involves multiple prepositions, each argument gets its own prepositional label.
+When each argument has its own relationship to the operation, each gets its
+own prepositional label:
 
 ```swift
-// GOOD
-database.move(item, from: source, to: destination)
-
-// GOOD
-view.transition(from: oldState, to: newState, duration: 0.3)
+shelf.move(book, from: source, to: destination)
+theme.transition(from: light, to: dark, duration: 0.3)
 ```
 
-## Grammatical Phrase Rule Extended Examples
+## Grammatical phrases
 
-When the first argument and base name form a grammatical phrase, omit the first label and absorb any leading words into the base name.
+If the first argument simply continues the sentence the base name began, it
+needs no label:
 
 ```swift
-// GOOD  -  "add subview"
-view.addSubview(child)
-
-// GOOD  -  "contains element"
-array.contains(element)
+stack.addSubview(child)
+tags.contains(element)
 ```
 
-### Absorbing leading words
-
-If the label would start with words that belong in the base name, move them.
+Words that would lead the label belong in the base name instead:
 
 ```swift
-// GOOD  -  "having length" absorbed into base name
-removeBoxes(havingLength: 12)
-
-// BAD  -  should be part of the base name
-remove(boxesHavingLength: 12)
+warehouse.removeBoxes(havingLength: 12)       // good
+warehouse.remove(boxesHavingLength: 12)       // avoid
 ```
 
-## Value-Preserving vs Narrowing Conversions
+## Conversions
 
-**Value-preserving (widening)**  -  the conversion cannot lose information. Omit the first label.
+### Value-preserving: no 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.
+The new value represents the old one exactly, so the call reads as a type
+conversion and nothing needs explaining.
 
 ```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
+Int64(someUInt32)
+String(someCharacter)
+Double(someFloat)
 ```
 
-**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
-```
+### Narrowing or lossy: a label that says how
 
-## Parameter Naming for Documentation
+| Initializer | What the label warns about |
+|---|---|
+| `Int64(truncating:)` | bits or precision are dropped |
+| `UInt32(clamping:)` | out-of-range values are pinned to the limits |
+| `String(describing:)` | a debug-style text description, not a value conversion |
+| `Int(exactly:)` | returns `nil` unless the value converts without loss |
 
-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.
+### A different representation: the label names the interpretation
 
 ```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?
+String(utf8String: cString)
+try Data(contentsOf: fileURL)
+URL(string: "https://example.com")
 ```
 
-Compare with a poorly named parameter:
+## Parameter names are documentation
+
+A parameter name may never appear at the call site, but it appears in the
+generated documentation and in the doc comment. Pick names that read well
+there.
 
 ```swift
-/// Finds the index of the equivalent element.
-///
-/// - Parameter e: ???
-func index(of e: Element) -> Int?
+extension Roster {
+    /// Returns the position of `member` in the roster, if present.
+    ///
+    /// - Parameter member: The person to look for.
+    /// - Returns: The index of `member`, or `nil` if they are not listed.
+    func index(of member: Person) -> Int? {
+        people.firstIndex(of: member)
+    }
+}
 ```
 
-Name parameters as complete English words. Single letters and abbreviations damage documentation quality.
+Compare `func index(of p: Person)`: the doc comment would have to talk about
+"`p`", which tells the reader nothing. Use whole English words for parameter
+names; single letters and abbreviations make the documentation worse.
 
-## Default Arguments Over Method Families
+## Default arguments instead of method families
 
-Prefer a single method with default parameter values over a family of methods.
+One method with defaults is easier to learn than several near-identical
+overloads:
 
 ```swift
-// GOOD  -  one method, sensible defaults
-func decode(
-    _ data: Data,
-    encoding: String.Encoding = .utf8,
-    allowLossyConversion: Bool = false
-) -> String?
+extension Transcoder {
+    func transcode(
+        _ video: Video,
+        preset: Preset = .standard,
+        preservesMetadata: Bool = true
+    ) async throws -> Video {
+        try await engine.run(video, preset: preset, metadata: preservesMetadata)
+    }
+}
+
+// Instead of transcode(_:), transcode(_:preset:) and
+// transcode(_:preset:preservesMetadata:)
 ```
 
+### Ordering
+
+Required parameters come first and defaulted ones last. The required
+parameters usually carry the meaning and form the grammatical core of the
+call, so they should read first:
+
 ```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?
+struct Glossary {
+    func lookup(
+        _ term: String,
+        in scope: Scope = .everything,
+        limit: Int = 25,
+        startingAt offset: Int = 0
+    ) -> [Entry] {
+        index.matches(for: term, in: scope).dropFirst(offset).prefix(limit).map { $0 }
+    }
+}
 ```
 
-### 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.
+Exception: a trailing closure that callers most often supply can follow the
+defaulted parameters, so it can still be written as a trailing closure.
 
 ```swift
-// GOOD  -  required parameters first
-func search(
-    query: String,
-    in scope: SearchScope = .all,
-    limit: Int = 50,
-    offset: Int = 0
-) -> [Result]
+final class SettingsStore {
+    func observe(
+        _ key: SettingKey,
+        initial: Bool = true,
+        onChange handler: @escaping (SettingValue) -> Void
+    ) -> Observation {
+        registry.add(key, emitsCurrentValue: initial, handler: handler)
+    }
+}
+
+// store.observe(.theme) { newValue in apply(newValue) }
 ```
-
-Exception: when a trailing closure is the most common override, it may come after defaulted parameters.