@coralai/sps-cli 0.41.2 → 0.43.0

package/skills/typescript/references/errors.md

@@ -0,0 +1,208 @@
+# TypeScript — Errors
+
+Error classes, `Result` types, catch semantics. For general strategy (when to raise vs return, where to log), see `coding-standards/references/error-strategy.md`.
+
+## Custom error classes
+
+Subclass `Error`. Always set `name`. Use `cause` to chain.
+
+```ts
+export class AppError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'AppError';
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(`${resource} not found`);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(public issues: { path: string; message: string }[]) {
+    super('validation failed');
+    this.name = 'ValidationError';
+  }
+}
+```
+
+Why `name`: stack traces use it, and `instanceof` can be unreliable across realms / duplicated module loads — the name string survives.
+
+## Chain with `cause`
+
+Preserve the original error (available in every modern runtime).
+
+```ts
+try {
+  await db.query(...);
+} catch (e) {
+  throw new AppError('failed to load user', { cause: e });
+}
+```
+
+Stack and `.cause` are both available for debugging / logging.
+
+## Catch `unknown`
+
+`catch (e)` in modern TS types `e` as `unknown`. Narrow before use.
+
+```ts
+try { ... } catch (e) {
+  if (e instanceof NotFoundError) return null;
+  if (e instanceof ValidationError) return { errors: e.issues };
+  throw e;                       // propagate the rest
+}
+```
+
+Never assume `e instanceof Error` without checking. Anything can be thrown — strings, numbers, `{}`, `null`.
+
+## `Result` types — optional, not always
+
+For operations where a failure is **expected**, a `Result` type makes the possibility visible in the signature and skips `try/catch`.
+
+```ts
+type Result<T, E> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+async function findUser(id: string): Promise<Result<User, 'not_found' | 'db_down'>> {
+  try {
+    const u = await db.users.find(id);
+    if (!u) return { ok: false, error: 'not_found' };
+    return { ok: true, value: u };
+  } catch (e) {
+    return { ok: false, error: 'db_down' };
+  }
+}
+
+const r = await findUser(id);
+if (!r.ok) return handle(r.error);
+use(r.value);
+```
+
+Libraries (`neverthrow`, `true-myth`) give you chainable `Result`s with more ergonomics.
+
+**When NOT to use**: if every caller re-throws the error anyway, `Result` just adds noise. Use it when the choice is local and important.
+
+## Mapping errors at the edge
+
+Internal: throw freely. Edge (HTTP handler, CLI main, queue consumer): translate into response.
+
+```ts
+// The one translation layer
+export function toHttpResponse(e: unknown): Response {
+  if (e instanceof ValidationError)
+    return json({ errors: e.issues }, { status: 422 });
+  if (e instanceof NotFoundError)
+    return json({ error: e.message }, { status: 404 });
+  if (e instanceof AuthError)
+    return json({ error: 'unauthorized' }, { status: 401 });
+
+  log.error('unexpected', { err: e });
+  return json({ error: 'internal error' }, { status: 500 });
+}
+```
+
+One place for the mapping. Handlers just throw.
+
+## Never silently swallow
+
+```ts
+// ❌ swallow
+try { doThing(); } catch { /* oops, silently ignored */ }
+
+// ✅ log and continue if that's really what you want
+try { doThing(); }
+catch (e) { log.warn('doThing failed', { err: e }); }
+
+// ✅ best: the caller decides
+```
+
+## `finally` for cleanup
+
+```ts
+const conn = await pool.acquire();
+try {
+  await work(conn);
+} finally {
+  conn.release();
+}
+```
+
+Don't put business logic in `finally` — it runs even on error.
+
+## Assertion helpers
+
+Cheap way to narrow + fail fast.
+
+```ts
+export function invariant(c: unknown, msg: string): asserts c {
+  if (!c) throw new AppError(`invariant failed: ${msg}`);
+}
+
+invariant(user.active, 'user must be active by this point');
+user.email;     // narrowed; no null check needed
+```
+
+Keep messages short and specific. `"user must be active"` beats `"check failed"`.
+
+## Error handling across async boundaries
+
+An error in an async function becomes a rejected promise. Don't mix sync `throw` with async rejection in a way callers can't predict.
+
+```ts
+// ❌ sometimes throws synchronously, sometimes rejects
+async function bad(x: unknown) {
+  if (!x) throw new Error('bad');    // rejection (we're in async)
+  return await f(x);                  // rejection
+}
+
+function worse(x: unknown) {
+  if (!x) throw new Error('bad');    // sync throw
+  return f(x);                        // returns a rejected promise
+}
+
+// ✅ consistently one or the other
+async function good(x: unknown) {
+  if (!x) throw new Error('bad');
+  return await f(x);
+}
+// callers can always `await good(x)` and catch both cases with try/catch
+```
+
+## Validation at boundaries
+
+Validate at parse time, never deep inside.
+
+```ts
+import { z } from 'zod';
+
+const Body = z.object({ email: z.string().email(), age: z.number().int().min(0) });
+
+export async function POST(req: Request) {
+  let input;
+  try {
+    input = Body.parse(await req.json());
+  } catch (e) {
+    return json({ errors: (e as z.ZodError).issues }, { status: 422 });
+  }
+  // inside the function, `input` is strongly typed and trusted
+  await service.signup(input);
+  return json({ ok: true });
+}
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `throw 'bad'` (string) | Always `throw new Error(...)` — strings lose stack |
+| `catch (e: any)` | Use `catch (e)` (unknown) + narrow |
+| `catch { return null }` | Log + handle specifically, or rethrow |
+| Checking error with `.message.includes('...')` | Use instanceof + a typed error class |
+| `Promise.reject('...')` with a string | Reject with an `Error` |
+| Over-broad error class hierarchy with 40 subtypes | Usually 5–8 is enough |
+| Error messages leaking PII / secrets | Redact before logging; never in client response |

package/skills/typescript/references/idioms.md

@@ -0,0 +1,246 @@
+# TypeScript — Idioms
+
+Destructuring, optional chaining, nullish coalescing, modules.
+
+## `const` / `let` / `var`
+
+`const` by default. `let` only when reassigning. Never `var` — it has function scope and hoisting surprises.
+
+```ts
+const MAX = 10;
+let count = 0;
+for (const x of xs) count += x;
+```
+
+## Destructuring
+
+```ts
+// Object
+const { id, email, name = 'unknown' } = user;
+
+// Array
+const [first, second, ...rest] = xs;
+
+// Rename + default
+const { id: userId, role = 'user' } = req;
+
+// Nested
+const { user: { id, email } } = response;
+```
+
+Avoid deep destructuring across many levels — it becomes hard to read. Two levels max.
+
+## Optional chaining (`?.`) and nullish coalescing (`??`)
+
+```ts
+const city = user?.address?.city;                 // undefined if any part is null/undef
+const port = config.port ?? 3000;                 // only falls back on null/undef
+const items = maybeResponse?.items ?? [];
+```
+
+Don't confuse `??` with `||`:
+
+```ts
+const port = config.port || 3000;   // also falls back on 0, '', false
+const port = config.port ?? 3000;   // only on null/undef
+```
+
+Use `||` when any falsy value should fall back; `??` when only "nothing" should.
+
+## Spread & rest
+
+```ts
+// Spread — copy + override
+const updated = { ...user, email: newEmail };
+const concat = [...xs, ...ys];
+
+// Rest in params
+function log(first: string, ...rest: unknown[]) { ... }
+
+// Rest in destructuring
+const { password, ...publicUser } = user;
+```
+
+Rest destructuring is a cheap way to drop a field (`publicUser` above).
+
+## Arrow vs. `function`
+
+- Arrow for callbacks, one-liners, closures that need lexical `this`.
+- `function` for top-level named functions that might be hoisted or recursive.
+
+```ts
+const double = (x: number) => x * 2;
+
+function fibonacci(n: number): number {
+  return n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
+}
+```
+
+## Immutable updates
+
+```ts
+// ❌ mutation
+user.email = newEmail;
+xs.push(item);
+
+// ✅ new value
+const updated = { ...user, email: newEmail };
+const next = [...xs, item];
+```
+
+Mutation is cheap but makes change hard to trace. In frontends (React, Vue) and any concurrent code, immutable updates are usually required, not optional.
+
+Use `structuredClone(x)` (global, Node 17+, browsers) for deep clones. Avoid `JSON.parse(JSON.stringify(x))` — loses dates, maps, undefined.
+
+## Modules — ESM, named exports
+
+Use ESM (`import` / `export`) everywhere. No `require` in new code (TS emits `require` if the target is CommonJS; that's a toolchain choice, not a source style).
+
+```ts
+// ✅ named exports — grep-friendly, IDEs auto-import
+export function parse(raw: string): Config { ... }
+export const DEFAULT_TIMEOUT = 5000;
+
+// ❌ default export + anonymous
+export default function (raw: string): Config { ... }
+```
+
+Default exports make renames invisible (`import Foo from './x'`) and break auto-import. Use named exports and let the import name match the export name.
+
+Allow `default` only when the language / framework demands it (React lazy routes, JSX component files by convention — team choice).
+
+## `for...of` over `.forEach`
+
+```ts
+// ✅ — supports `await`, `break`, `continue`, `return`
+for (const x of xs) {
+  await process(x);
+  if (done) break;
+}
+
+// ⚠️ .forEach ignores `return` and can't be awaited
+xs.forEach(async x => await process(x));   // fires in parallel; next line doesn't wait
+```
+
+`forEach` is fine for pure synchronous side effects on small arrays. For anything else, `for...of`.
+
+## Map / Set over object / array when keys aren't known strings
+
+```ts
+// ❌ object-as-map
+const counts: Record<string, number> = {};
+counts[key] = (counts[key] ?? 0) + 1;
+// keys stringified; `constructor`, `__proto__` are footguns
+
+// ✅ Map
+const counts = new Map<string, number>();
+counts.set(key, (counts.get(key) ?? 0) + 1);
+```
+
+Use `Map` when keys are dynamic, need iteration in insertion order, or aren't strings. Use `Set` for unique values.
+
+## JSON at boundaries
+
+Parse with a schema; never trust `JSON.parse(raw) as Config`.
+
+```ts
+// ❌
+const config: Config = JSON.parse(raw);    // wrong at runtime; TS can't stop it
+
+// ✅
+const config = ConfigSchema.parse(JSON.parse(raw));   // zod throws on bad data
+```
+
+## String templates
+
+Backticks for interpolation and multi-line.
+
+```ts
+const msg = `Hello ${name}, you have ${count} messages`;
+
+const html = `
+  <div>
+    ${items.map(i => `<li>${i.name}</li>`).join('')}
+  </div>
+`;
+```
+
+For anything user-controlled rendered into HTML/SQL/shell, you need escaping, not templates. Templates are for formatting, not safety.
+
+## Narrowing with `in`
+
+```ts
+function area(s: Circle | Square) {
+  if ('radius' in s) return Math.PI * s.radius ** 2;
+  return s.side ** 2;
+}
+```
+
+`in` narrows to the variant that has the property. Works well with discriminated unions too, but `.kind` / `.type` discriminators are clearer.
+
+## Short-circuit guards
+
+Prefer guards at the top to deep nesting.
+
+```ts
+function process(user: User | null) {
+  if (!user) return null;
+  if (!user.active) return null;
+  return doWork(user);
+}
+```
+
+## Assertion functions
+
+Marks a path as unreachable without narrowing.
+
+```ts
+function assert(c: unknown, msg: string): asserts c {
+  if (!c) throw new Error(msg);
+}
+
+const x: string | null = maybe();
+assert(x !== null, 'x must be set by now');
+x.toLowerCase();           // narrowed to string
+```
+
+## `bigint`, `Date`, and friends
+
+- `Date` has sharp edges (month 0-indexed, mutation). Prefer a lib (`date-fns`, `luxon`, native `Temporal` when widely available).
+- `bigint` for integers > 2^53. Mixing `bigint` and `number` is a type error — good.
+- `Symbol` — useful for unique keys and well-known protocols. Rarely needed in application code.
+
+## `void` vs `undefined` in return types
+
+- `void` for "I don't care what you return" (callbacks whose return is ignored).
+- `undefined` when the function explicitly returns nothing.
+
+```ts
+function subscribe(cb: () => void) { ... }
+// subscriber may return something; we ignore it.
+
+function log(msg: string): undefined {
+  console.log(msg);
+  return;
+}
+```
+
+Trivia, but CR-worthy in library code.
+
+## `this` — lexical or bound, never `function` inside callbacks
+
+```ts
+// ❌ `this` is whatever called the callback
+btn.addEventListener('click', function() { this.count++ });
+
+// ✅ lexical `this` via arrow
+btn.addEventListener('click', () => { this.count++ });
+```
+
+In classes, use `.bind(this)` at construction time, or use arrow-method field syntax:
+
+```ts
+class X {
+  handle = () => { /* `this` is X, always */ };
+}
+```

package/skills/typescript/references/testing.md

@@ -0,0 +1,225 @@
+# TypeScript — Testing
+
+Vitest / Jest, mocking, fixtures. For TDD cycle and general philosophy, see `coding-standards/references/tdd.md`.
+
+## Runner: Vitest > Jest (for new projects)
+
+Vitest is faster, ESM-native, and shares config with Vite. Jest is still fine on existing code.
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    coverage: { provider: 'v8', reporter: ['text', 'html'], thresholds: { lines: 80 } },
+    globals: false,            // import describe/it/expect explicitly
+  },
+});
+```
+
+## File layout
+
+| Convention | Pattern |
+|---|---|
+| Colocated | `src/user.ts` + `src/user.test.ts` |
+| Separated | `src/user.ts` + `tests/user.test.ts` |
+
+Colocated is easier to maintain; separated is easier to exclude from production bundles (if your bundler doesn't already tree-shake tests). Pick one and be consistent.
+
+## Structure
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { UserService } from './user-service';
+
+describe('UserService', () => {
+  let service: UserService;
+
+  beforeEach(() => {
+    service = new UserService(new InMemoryUserRepo());
+  });
+
+  it('creates a user with a generated id', async () => {
+    const u = await service.create({ name: 'A', email: 'a@x.com' });
+    expect(u.id).toBeTypeOf('string');
+    expect(u.name).toBe('A');
+  });
+
+  it('rejects empty email', async () => {
+    await expect(service.create({ name: 'A', email: '' }))
+      .rejects.toThrow(ValidationError);
+  });
+});
+```
+
+Test names describe behaviour, not implementation. `creates a user with a generated id`, not `test_1`.
+
+## Assertions
+
+```ts
+expect(value).toBe(expected);                  // strict equality (===)
+expect(value).toEqual(expected);               // deep equality
+expect(value).toStrictEqual(expected);         // deep + prototype + undefined
+
+expect(fn).toThrow(TypeError);
+expect(fn).toThrow(/invalid email/);
+await expect(promise).rejects.toThrow();
+
+expect(array).toContain(item);
+expect(obj).toMatchObject({ name: 'A' });      // partial match
+
+expect(value).toSatisfy(v => v > 0 && v < 10);
+```
+
+`toBe` on objects compares references, almost always wrong. Use `toEqual`.
+
+## Mocking
+
+Prefer fakes (real implementations with in-memory backing) over mocks. Mocks drift from the thing they imitate.
+
+```ts
+// ✅ fake — behaves like a repo, just in memory
+class InMemoryUserRepo implements UserRepository {
+  private users = new Map<string, User>();
+  async findById(id: string) { return this.users.get(id) ?? null; }
+  async save(u: User) { this.users.set(u.id, u); }
+}
+
+// ⚠️ mock — easy for one test, painful when the repo grows
+const mockRepo = {
+  findById: vi.fn().mockResolvedValue(null),
+  save:     vi.fn(),
+} as unknown as UserRepository;
+```
+
+When you do mock:
+
+```ts
+import { vi } from 'vitest';
+
+const sendEmail = vi.fn();
+vi.mock('./email', () => ({ sendEmail }));
+
+it('sends welcome email', async () => {
+  await service.signup('a@x.com');
+  expect(sendEmail).toHaveBeenCalledWith({ to: 'a@x.com', template: 'welcome' });
+});
+```
+
+`vi.mock` hoists — the import is replaced everywhere the module is used.
+
+## Fixtures — inject what the test needs
+
+```ts
+function makeUser(overrides: Partial<User> = {}): User {
+  return { id: 'u_1', email: 'a@x.com', active: true, ...overrides };
+}
+
+it('rejects inactive users', () => {
+  const u = makeUser({ active: false });
+  expect(() => assertActive(u)).toThrow();
+});
+```
+
+Factories beat hard-coded objects. Default in place, override per test.
+
+## Parameterized tests
+
+```ts
+describe.each([
+  { a: 1, b: 2, sum: 3 },
+  { a: 0, b: 0, sum: 0 },
+  { a: -1, b: 1, sum: 0 },
+])('add($a, $b)', ({ a, b, sum }) => {
+  it(`returns ${sum}`, () => expect(add(a, b)).toBe(sum));
+});
+```
+
+Use `it.each` for simpler cases.
+
+## Async tests
+
+```ts
+it('fetches', async () => {
+  const u = await findUser('u_1');
+  expect(u).not.toBeNull();
+});
+
+// Rejections
+await expect(findUser('bad')).rejects.toThrow(NotFoundError);
+
+// Don't forget `await`; a missing `await` on a rejecting promise is a silent false pass
+```
+
+Fake timers for time-based code:
+
+```ts
+vi.useFakeTimers();
+const p = sleep(1000).then(() => 'done');
+vi.advanceTimersByTime(1000);
+await expect(p).resolves.toBe('done');
+vi.useRealTimers();
+```
+
+## Snapshot tests — use sparingly
+
+```ts
+expect(renderEmail(user)).toMatchSnapshot();
+```
+
+Good for large structural output. Bad as a lazy "assert-something" catch-all — a stale snapshot silently legitimizes bugs.
+
+Review every snapshot change deliberately. If you're running `--update-snapshots` as a reflex, they've lost their value.
+
+## Integration tests
+
+Hit real dependencies (DB, Redis, HTTP) where feasible. Testcontainers makes this portable.
+
+```ts
+// tests/integration/user.test.ts
+import { GenericContainer } from 'testcontainers';
+
+let pg;
+beforeAll(async () => {
+  pg = await new GenericContainer('postgres:16-alpine')
+    .withEnvironment({ POSTGRES_PASSWORD: 'test' })
+    .withExposedPorts(5432)
+    .start();
+  // set DB_URL from pg.getMappedPort(5432)
+});
+afterAll(() => pg.stop());
+```
+
+Integration tests give confidence that unit tests alone can't. Keep them separate from unit tests (`tests/integration/**`) so CI can run them in a different stage.
+
+## Coverage — a floor, not a goal
+
+See `coding-standards/references/tdd.md` for coverage targets. Chasing 100% coverage with meaningless assertions hurts more than it helps.
+
+Enforce in CI:
+
+```ts
+// vitest.config.ts
+test: {
+  coverage: {
+    thresholds: {
+      lines: 80,
+      functions: 80,
+      branches: 70,
+    },
+  },
+}
+```
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Tests that sleep for real seconds | Fake timers |
+| `it.only` committed to main | CI rule: reject `.only` in `test`/`it`/`describe` |
+| Shared mutable state between tests | Reset in `beforeEach` |
+| Testing by spying on console.log | Test observable behaviour, not debug output |
+| `expect(x).toEqual(x)` | Tautology; no signal |
+| Over-mocking: 10 mocks to test 20 lines | Refactor so the unit is easier to test |
+| Network in unit tests | Use fakes; move to integration suite |
+| Snapshot tests for volatile output (dates, uuids) | Redact or use deterministic fixtures |