@coralai/sps-cli 0.41.2 → 0.43.0

package/skills/swift/references/testing.md

@@ -0,0 +1,229 @@
+# Swift — Testing
+
+XCTest and Swift Testing (Swift 6+). For TDD, see `coding-standards/references/tdd.md`.
+
+## Runner choice
+
+- **XCTest** — mature, ships with Xcode, required for UI tests.
+- **Swift Testing** — Swift 6 stdlib, cleaner API, macros for parametrized tests. Use for new unit tests when your toolchain supports it.
+
+Both can coexist in the same target.
+
+## XCTest
+
+```swift
+import XCTest
+@testable import MyApp
+
+final class UserServiceTests: XCTestCase {
+    func test_createUser_returnsPersistedUser() async throws {
+        let service = UserService(repo: InMemoryUserRepo())
+        let user = try await service.create(email: "a@x.com")
+        XCTAssertEqual(user.email, "a@x.com")
+        XCTAssertFalse(user.id.isEmpty)
+    }
+
+    func test_createUser_rejectsEmptyEmail() async {
+        let service = UserService(repo: InMemoryUserRepo())
+        do {
+            _ = try await service.create(email: "")
+            XCTFail("expected ValidationError")
+        } catch is ValidationError {
+            // expected
+        } catch {
+            XCTFail("unexpected error: \(error)")
+        }
+    }
+}
+```
+
+Name tests `test_behaviour_expectation`. Structure: **Arrange → Act → Assert**.
+
+## Swift Testing (Swift 6+)
+
+```swift
+import Testing
+@testable import MyApp
+
+struct UserServiceTests {
+    @Test
+    func createUserReturnsPersistedUser() async throws {
+        let service = UserService(repo: InMemoryUserRepo())
+        let user = try await service.create(email: "a@x.com")
+        #expect(user.email == "a@x.com")
+        #expect(!user.id.isEmpty)
+    }
+
+    @Test
+    func createUserRejectsEmptyEmail() async throws {
+        let service = UserService(repo: InMemoryUserRepo())
+        await #expect(throws: ValidationError.self) {
+            try await service.create(email: "")
+        }
+    }
+}
+```
+
+Cleaner: `#expect(...)` macro, `@Test` annotation, real async support.
+
+## Parametrized tests
+
+```swift
+@Test("add cases", arguments: [
+    (1, 2, 3),
+    (0, 0, 0),
+    (-1, 1, 0),
+])
+func add(a: Int, b: Int, expected: Int) {
+    #expect(MyApp.add(a, b) == expected)
+}
+```
+
+XCTest equivalent requires manual loops or `XCTestCase` subclasses.
+
+## Assertions
+
+| XCTest | Swift Testing |
+|---|---|
+| `XCTAssertEqual(a, b)` | `#expect(a == b)` |
+| `XCTAssertTrue(x)` | `#expect(x)` |
+| `XCTAssertNil(x)` | `#expect(x == nil)` |
+| `XCTAssertThrowsError { ... }` | `#expect(throws: ...) { ... }` |
+| `XCTFail("msg")` | `Issue.record("msg")` |
+
+## Fakes over mocks
+
+Hand-roll fakes; Swift's strong type system makes them cheap.
+
+```swift
+final class InMemoryUserRepo: UserRepositoryProtocol {
+    private var users: [String: User] = [:]
+    func find(id: String) async -> User? { users[id] }
+    func save(_ u: User) async { users[u.id] = u }
+}
+```
+
+For mock libraries, `Cuckoo` and `Mockable` exist; most teams find hand-rolled cheaper in Swift than in JVM.
+
+## Async tests
+
+Swift Testing supports `async` natively. XCTest also, from iOS 13+ / macOS 10.15+:
+
+```swift
+func test_loads() async throws {
+    let user = try await service.load(id: "u1")
+    XCTAssertEqual(user.id, "u1")
+}
+```
+
+For code using completion callbacks (legacy), use `XCTestExpectation`:
+
+```swift
+func test_legacy() {
+    let exp = expectation(description: "callback")
+    legacy { result in
+        XCTAssertNotNil(result)
+        exp.fulfill()
+    }
+    wait(for: [exp], timeout: 5)
+}
+```
+
+New code shouldn't need this — bridge to `async` with `withCheckedContinuation`.
+
+## Timing / clock control
+
+Mock time with a `Clock` protocol:
+
+```swift
+protocol Clock { func now() -> Date }
+
+final class FixedClock: Clock {
+    var time: Date
+    init(_ t: Date) { self.time = t }
+    func now() -> Date { time }
+}
+```
+
+For `Task.sleep` in tests, use `ContinuousClock` with a manually advanced test clock (Swift Testing / swift-async-algorithms).
+
+Swift Testing integrates with the new `Clock` primitives and supports virtual time.
+
+## UI tests — XCUITest
+
+```swift
+final class AppUITests: XCTestCase {
+    func test_login_success() {
+        let app = XCUIApplication()
+        app.launch()
+        app.textFields["email"].tap()
+        app.textFields["email"].typeText("a@x.com")
+        app.buttons["Continue"].tap()
+        XCTAssertTrue(app.staticTexts["Welcome"].waitForExistence(timeout: 5))
+    }
+}
+```
+
+Rules:
+- Use `accessibilityIdentifier`, not labels — labels break when copy changes.
+- Reset app state in `setUp`; UI tests are order-dependent if you don't.
+- Keep to happy paths and critical flows; they're slow and brittle.
+
+## Snapshot tests
+
+`swift-snapshot-testing` (`point-free`) for views, JSON, formatted strings.
+
+```swift
+import SnapshotTesting
+import XCTest
+
+final class UserViewTests: XCTestCase {
+    func test_userView() {
+        let vc = UserViewController(user: .sample)
+        assertSnapshot(matching: vc, as: .image)
+    }
+}
+```
+
+Review diffs deliberately; don't mass-accept.
+
+## Coverage
+
+Xcode can emit `.xcresult` with coverage; `xcrun xccov view --report` for CLI. Set a threshold in your `fastlane` / CI.
+
+## Performance tests
+
+```swift
+func test_perf_parsing() {
+    measure {
+        _ = parse(sampleInput)
+    }
+}
+```
+
+Xcode stores baselines; regressions highlight on re-run. Keep perf tests to critical paths; they're slow and machine-dependent.
+
+## Test plans
+
+Use Xcode test plans to split fast unit tests, slower integration, UI tests into separate CI stages:
+
+```
+UnitTests.xctestplan           # fast, ~seconds
+IntegrationTests.xctestplan    # real deps, minutes
+UITests.xctestplan             # UI, slow
+```
+
+Run unit on every PR; integration and UI on merge-to-main.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `Thread.sleep` / `sleep()` in tests to wait for async | `XCTestExpectation` or `async/await` |
+| `try!` inside a test | Use `try` + `XCTAssertNoThrow` or Swift Testing `#expect(throws:)` |
+| Shared state across tests via singletons | Reset in `setUp`; prefer DI |
+| Snapshot test accepted without review | Always diff before committing |
+| UI tests finding by label (`"Log in"`) | Use `accessibilityIdentifier` |
+| Mocking the thing you're testing | Test via real public API |
+| `XCTFail` + guard + `return` scattered inline | Use Swift Testing `#expect(throws:)` or helper methods |
+| Tests depending on device locale / time | Inject locale / clock |

package/skills/typescript/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: typescript
+description: TypeScript language skill — types, idioms, async, tooling. Pair with end skills (`backend`, `frontend`, `mobile`) for architecture and with `coding-standards` for cross-language principles.
+origin: ecc-fork + original (https://github.com/affaan-m/everything-claude-code, MIT)
+---
+
+# TypeScript
+
+Type system, idioms, async, tooling. **Language-focused**. Architecture belongs to end skills; general principles (TDD, naming, error strategy) live in `coding-standards`.
+
+## When to load
+
+- Project primary language is TypeScript (Node.js / Deno / Bun / browser)
+- Reviewing TS code
+- Designing types, generics, discriminated unions
+- Setting up `tsconfig.json`, build, test tooling
+
+## Core principles
+
+1. **`strict: true`, always.** Non-negotiable. The rest of TS is barely worth using without it.
+2. **No `any`.** Use `unknown` + narrowing if you don't know the shape. Every `any` in review gets a blocker.
+3. **Types describe intent.** Prefer `UserId` branded type over bare `string`; use discriminated unions over boolean flags.
+4. **Inference first.** Let TS infer; add annotations on public signatures and where inference is wrong or opaque.
+5. **`const` by default, `let` only when reassigning.** Never `var`.
+6. **Immutability where practical.** `readonly` on fields, `ReadonlyArray<T>` for inputs.
+7. **`===` only.** `==` has JS quirks; there is no legitimate reason to use it in new code.
+8. **Explicit error types at boundaries** (HTTP, queue, FFI). Inside, throw freely.
+
+## How to use references
+
+| Reference | When to load |
+|---|---|
+| [`references/types.md`](references/types.md) | Generics, unions, discriminated unions, conditional types, utility types, brands |
+| [`references/idioms.md`](references/idioms.md) | Destructuring, optional chaining, nullish coalescing, modules, enums vs. union |
+| [`references/async.md`](references/async.md) | Promises, async/await, error propagation, cancellation (AbortController), concurrency |
+| [`references/errors.md`](references/errors.md) | Error classes, `Result` / `neverthrow`, `try/catch`, re-throw semantics |
+| [`references/testing.md`](references/testing.md) | Vitest / Jest, mocking, fixtures, integration tests |
+| [`references/tooling.md`](references/tooling.md) | `tsconfig`, ESLint, formatter, bundlers, monorepo layout |
+
+## Forbidden patterns (auto-reject)
+
+- `any` without a comment explaining why
+- `as X` casts without runtime validation (use a schema validator at boundaries)
+- `==` / `!=`
+- `var`
+- Unhandled promise (`.then()` without `.catch()`, or an `await` without containing `try`)
+- `Function` / `Object` as a type
+- Default-exporting everything in new code (named exports — one public name per import)
+- Enums for string constants (use literal string unions instead — smaller, tree-shakeable)
+- Mutating function parameters
+- `console.log` left in committed code

package/skills/typescript/references/async.md

@@ -0,0 +1,241 @@
+# TypeScript — Async
+
+Promises, async/await, error propagation, cancellation, concurrency.
+
+## `async/await` is sugar for promises
+
+```ts
+// These are equivalent
+async function f() { const x = await g(); return x + 1; }
+function f()      { return g().then(x => x + 1); }
+```
+
+Prefer `async/await` for linear flows, `.then` chains for pipelines on a single value.
+
+## Every promise must be awaited or handled
+
+Unhandled rejections crash Node (in strict mode) or log cryptic warnings.
+
+```ts
+// ❌ fire-and-forget
+sendEmail(user.email);           // if it rejects → unhandled
+doThing().then(logSuccess);      // no .catch
+
+// ✅
+await sendEmail(user.email);
+
+// ✅ intentional fire-and-forget: use .catch
+void sendEmail(user.email).catch(err => log.error(err));
+```
+
+TS/ESLint rules: `@typescript-eslint/no-floating-promises` catches these.
+
+## Error propagation
+
+Throws inside `async` become rejections. `try/catch` catches them.
+
+```ts
+async function load() {
+  try {
+    const r = await fetch(url);
+    if (!r.ok) throw new HttpError(r.status);
+    return await r.json();
+  } catch (e) {
+    if (e instanceof HttpError && e.status === 404) return null;
+    throw e;
+  }
+}
+```
+
+`catch (e: unknown)` — always. `e` is not an `Error` in JS; could be anything thrown.
+
+```ts
+try { ... } catch (e) {
+  if (e instanceof Error) log.error(e.message);
+  else log.error('non-Error thrown', { e });
+}
+```
+
+## Concurrency
+
+### Parallel, all must succeed
+
+```ts
+const [u, o, p] = await Promise.all([
+  getUser(id),
+  getOrders(id),
+  getPrefs(id),
+]);
+```
+
+One rejection → whole thing rejects; other in-flight promises continue but their results are discarded.
+
+### Parallel, any may fail
+
+```ts
+const results = await Promise.allSettled(tasks);
+for (const r of results) {
+  if (r.status === 'fulfilled') use(r.value);
+  else log.warn(r.reason);
+}
+```
+
+### First to finish wins
+
+```ts
+const winner = await Promise.race([req, timeout(5000)]);
+```
+
+### First to succeed (any)
+
+```ts
+const first = await Promise.any([primary(), secondary(), tertiary()]);
+// rejects only if all fail
+```
+
+## Sequential vs. parallel — don't accidentally serialize
+
+```ts
+// ❌ serial (each waits for the prior)
+for (const id of ids) {
+  await fetchUser(id);
+}
+
+// ✅ parallel
+await Promise.all(ids.map(fetchUser));
+```
+
+Sequential is correct when order matters or when you want backpressure. Parallel is often what you wanted but wrote wrong.
+
+## Bounded parallelism
+
+Unlimited parallelism blows up memory and hammers downstreams. Bound it.
+
+```ts
+import pLimit from 'p-limit';
+
+const limit = pLimit(10);
+const results = await Promise.all(ids.map(id => limit(() => fetchUser(id))));
+```
+
+Or chunk manually:
+
+```ts
+async function inChunks<T, R>(xs: T[], size: number, fn: (x: T) => Promise<R>) {
+  const out: R[] = [];
+  for (let i = 0; i < xs.length; i += size) {
+    const chunk = xs.slice(i, i + size);
+    out.push(...await Promise.all(chunk.map(fn)));
+  }
+  return out;
+}
+```
+
+## Cancellation — `AbortController`
+
+The standard cancellation primitive for fetch, streams, timers.
+
+```ts
+const ac = new AbortController();
+setTimeout(() => ac.abort(), 5000);
+
+try {
+  const r = await fetch(url, { signal: ac.signal });
+  return await r.json();
+} catch (e) {
+  if (e instanceof DOMException && e.name === 'AbortError') {
+    // cancelled
+  } else {
+    throw e;
+  }
+}
+```
+
+For your own async functions, accept a `signal` and check / propagate it:
+
+```ts
+async function work({ signal }: { signal?: AbortSignal }) {
+  if (signal?.aborted) throw new DOMException('aborted', 'AbortError');
+  signal?.addEventListener('abort', () => { /* clean up */ }, { once: true });
+  ...
+}
+```
+
+## Timeouts — `AbortSignal.timeout` (modern)
+
+```ts
+const r = await fetch(url, { signal: AbortSignal.timeout(5000) });
+```
+
+Falls back to `AbortController` + `setTimeout` on older runtimes.
+
+## Retry with backoff
+
+```ts
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  { attempts = 3, baseMs = 100, maxMs = 10_000 } = {},
+): Promise<T> {
+  for (let i = 0; i < attempts; i++) {
+    try { return await fn(); }
+    catch (e) {
+      if (i === attempts - 1) throw e;
+      const delay = Math.min(maxMs, baseMs * 2 ** i) * (0.5 + Math.random());
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+
+Only retry idempotent operations. See `backend/references/resilience.md`.
+
+## Async iterators & streams
+
+For data you consume one chunk at a time.
+
+```ts
+async function* readLines(stream: ReadableStream<Uint8Array>) {
+  const decoder = new TextDecoder();
+  const reader = stream.getReader();
+  let buf = '';
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.split('\n');
+    buf = lines.pop()!;
+    for (const line of lines) yield line;
+  }
+  if (buf) yield buf;
+}
+
+for await (const line of readLines(resp.body!)) {
+  process(line);
+}
+```
+
+## Microtasks & the event loop
+
+`await` queues continuation as a microtask — runs before macro-tasks (`setTimeout`) even at delay 0.
+
+```ts
+Promise.resolve().then(() => console.log('A'));   // microtask
+setTimeout(() => console.log('B'), 0);             // macrotask
+// A then B
+```
+
+You rarely need to know this, until you're debugging an out-of-order log.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `new Promise((res) => { ... res(x) })` wrapping a callback API | Use `util.promisify` (Node) or a library wrapper |
+| Rejecting with a string | Always `new Error(...)` |
+| Nested `.then` chains | Flatten with `await` |
+| `.catch` without re-throw on unknown errors | Narrow or rethrow |
+| `await` inside a `.forEach` | Use `for...of` or `Promise.all` |
+| `async` function returning `Promise<Promise<T>>` | Unnecessary; one `async` is enough |
+| Dangling `setTimeout`/`setInterval` in React effects | Return cleanup or use a library |
+| Fire-and-forget without `.catch` | Silent failures; add `.catch(log)` |