@coralai/sps-cli 0.55.12 → 0.56.0

package/skills/typescript/references/testing.md

@@ -1,225 +0,0 @@
-# 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 |

package/skills/typescript/references/tooling.md

@@ -1,208 +0,0 @@
-# TypeScript — Tooling
-
-`tsconfig`, linting, formatting, bundlers, monorepos.
-
-## `tsconfig.json` — the baseline
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-    "exactOptionalPropertyTypes": true,
-
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["**/*.test.ts", "dist"]
-}
-```
-
-Key switches:
-
-| Option | Why |
-|---|---|
-| `strict: true` | Turns on all strict flags. Required. |
-| `noUncheckedIndexedAccess` | `arr[0]` returns `T \| undefined`. Prevents off-by-one bugs. |
-| `exactOptionalPropertyTypes` | `{ x?: number }` vs `{ x: number \| undefined }` are actually different. |
-| `isolatedModules` | Required for swc/esbuild/bun. Catches things the single-file compilers can't handle. |
-| `skipLibCheck: true` | Faster; trust your deps. |
-
-## Node vs. bundler resolution
-
-`moduleResolution: "Bundler"` for Vite, esbuild, webpack, Vite, Bun. `"NodeNext"` for plain Node.js. Pick based on the runtime.
-
-## Path aliases
-
-```json
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"]
-    }
-  }
-}
-```
-
-Mirror this in the bundler and test runner, or imports resolve in TS but not at runtime.
-
-## Linting — ESLint (flat config)
-
-```js
-// eslint.config.js
-import tseslint from 'typescript-eslint';
-export default tseslint.config(
-  ...tseslint.configs.recommendedTypeChecked,
-  {
-    languageOptions: { parserOptions: { project: true } },
-    rules: {
-      '@typescript-eslint/no-floating-promises': 'error',
-      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-      '@typescript-eslint/switch-exhaustiveness-check': 'error',
-      '@typescript-eslint/consistent-type-imports': 'error',
-      '@typescript-eslint/no-explicit-any': 'error',
-    },
-  },
-);
-```
-
-High-signal rules:
-- `no-floating-promises` — forgotten `await` is a frequent bug
-- `switch-exhaustiveness-check` — forgotten case in a union switch
-- `no-misused-promises` — `async` callback passed where sync is expected
-- `consistent-type-imports` — `import type { X }` keeps runtime lean
-
-## Formatting — Prettier (or project-specific)
-
-Let the formatter run in CI and on save. Don't argue style in PRs.
-
-```json
-// .prettierrc
-{
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "all",
-  "printWidth": 100,
-  "arrowParens": "always"
-}
-```
-
-Team preference is fine — the choice matters less than the consistency.
-
-## `tsc` vs. the bundlers
-
-| Tool | Role |
-|---|---|
-| `tsc` | Type checking + `.d.ts` emit |
-| `esbuild` / `swc` | Fast transpile (strip types, downlevel syntax) |
-| `tsup` / `rollup` | Libraries with exports maps |
-| `vite` / `rsbuild` / `rspack` | App bundling (frontend / dev server) |
-
-Typical modern setup: `vitest` for tests, `vite` for the dev server, `tsc --noEmit` in CI for type checking. Transpile is handled by the bundler — `tsc` is not on the hot path.
-
-## Package managers
-
-`pnpm` is the default recommendation:
-- Content-addressable store → disk savings, fast installs
-- Strict by default → catches phantom dependencies
-- Excellent monorepo support via workspaces
-
-`npm` works. `yarn classic` (v1) is deprecated; `yarn berry` (v3+) is fine but niche. `bun` is fastest but still rough around the edges for some toolchains.
-
-Commit the lockfile.
-
-## Monorepo
-
-For 3+ packages that share code, use workspaces.
-
-```json
-// package.json (root)
-{
-  "private": true,
-  "workspaces": ["packages/*", "apps/*"]
-}
-```
-
-Prefer workspace tools over hand-rolled symlinks:
-- `pnpm` workspaces (native)
-- `turborepo` / `nx` for task orchestration + caching
-- `changesets` for versioning + release notes
-
-Keep the dependency graph explicit — `apps/web` depends on `packages/ui`, not the reverse.
-
-## `package.json` essentials
-
-```json
-{
-  "name": "@org/pkg",
-  "version": "1.2.0",
-  "type": "module",
-  "exports": {
-    ".":         { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./utils":   { "types": "./dist/utils.d.ts", "import": "./dist/utils.js" }
-  },
-  "files": ["dist"],
-  "scripts": {
-    "build":     "tsup src/index.ts --format esm --dts",
-    "test":      "vitest run",
-    "lint":      "eslint .",
-    "typecheck": "tsc --noEmit"
-  },
-  "engines": { "node": ">=20" }
-}
-```
-
-- `type: "module"` — ESM by default. New projects should be ESM.
-- `exports` — explicit public API, not "everything in the dist directory".
-- `engines` — fail loudly when users install on an unsupported Node.
-
-## Dev vs. prod dependencies
-
-- `dependencies`: anything the shipped app actually runs
-- `devDependencies`: build tools, test frameworks, types
-- `peerDependencies`: libraries (only) — "I need X, user provides it"
-
-A library that ships `react` in `dependencies` causes duplicate-React bugs. Put it in `peerDependencies` with a loose range.
-
-## CI checklist
-
-```yaml
-# GitHub Actions sketch
-- run: pnpm install --frozen-lockfile
-- run: pnpm typecheck
-- run: pnpm lint
-- run: pnpm test --coverage
-- run: pnpm build
-```
-
-Order matters: typecheck before tests (cheap fail); lint before tests (cheap fail); build last.
-
-## Anti-patterns
-
-| Anti-pattern | Fix |
-|---|---|
-| `strict: false` | Turn it on; fix errors incrementally with `// @ts-expect-error` |
-| `tsc` on every file save in a large repo | Use `--incremental` or IDE's language server |
-| Leaving `skipLibCheck: false` | Fine for a tiny project; wastes CI on any larger one |
-| Committing `dist/` | Publish it, don't commit it |
-| `type: "commonjs"` in new projects | Go ESM |
-| Mixing formatters across directories | One config at the repo root |
-| `ts-node` in production | Pre-compile; don't transpile at boot |

package/skills/typescript/references/types.md

@@ -1,259 +0,0 @@
-# TypeScript — Types
-
-Generics, unions, discriminated unions, utility types, brands.
-
-## `unknown` over `any`
-
-`any` disables type checking. `unknown` forces you to narrow before use.
-
-```ts
-// ❌ silent bugs
-function parse(raw: any) {
-  return raw.user.email.toLowerCase();   // crashes at runtime, no TS error
-}
-
-// ✅
-function parse(raw: unknown) {
-  if (typeof raw === 'object' && raw !== null && 'user' in raw) {
-    // ... still need more narrowing
-  }
-}
-
-// ✅✅ parse at boundary with a schema
-import { z } from 'zod';
-const Schema = z.object({ user: z.object({ email: z.string().email() }) });
-function parse(raw: unknown) {
-  const { user } = Schema.parse(raw);    // throws on bad shape
-  return user.email.toLowerCase();
-}
-```
-
-## Discriminated unions — the TS superpower
-
-Model state with a tagged sum type. Narrowing happens automatically.
-
-```ts
-type Result<T, E> =
-  | { ok: true; value: T }
-  | { ok: false; error: E };
-
-function handle(r: Result<User, Error>) {
-  if (r.ok) {
-    // r is narrowed to { ok: true; value: User }
-    console.log(r.value.name);
-  } else {
-    // r is narrowed to { ok: false; error: Error }
-    console.error(r.error.message);
-  }
-}
-```
-
-Prefer over boolean flags + optional fields:
-
-```ts
-// ❌
-type Loading = { isLoading: boolean; data?: User; error?: string };
-
-// ✅
-type Loading =
-  | { status: 'idle' }
-  | { status: 'loading' }
-  | { status: 'success'; data: User }
-  | { status: 'error'; error: string };
-```
-
-The compiler stops you from accessing `data` on an `error` state.
-
-## Exhaustiveness checks
-
-When you switch over a union, make sure every case is handled.
-
-```ts
-function render(r: Loading) {
-  switch (r.status) {
-    case 'idle':    return <Idle />;
-    case 'loading': return <Spinner />;
-    case 'success': return <Show data={r.data} />;
-    case 'error':   return <Err msg={r.error} />;
-    default:        return assertNever(r);
-  }
-}
-
-function assertNever(x: never): never {
-  throw new Error(`Unreachable: ${JSON.stringify(x)}`);
-}
-```
-
-Add a new variant → the compiler forces you to update every `switch`.
-
-## Generics
-
-Use when a function / class preserves a type relationship.
-
-```ts
-function first<T>(xs: readonly T[]): T | undefined {
-  return xs[0];
-}
-
-// Bounded
-function byId<T extends { id: string }>(xs: T[], id: string): T | undefined {
-  return xs.find(x => x.id === id);
-}
-
-// Default
-type Paginated<T, Cursor = string> = {
-  data: T[];
-  nextCursor: Cursor | null;
-};
-```
-
-If a generic parameter appears only once in the signature, you probably don't need generics.
-
-## Utility types — the greatest hits
-
-| Type | Use |
-|---|---|
-| `Partial<T>` | All fields optional |
-| `Required<T>` | All fields required |
-| `Readonly<T>` | All fields readonly |
-| `Pick<T, K>` | Subset of fields |
-| `Omit<T, K>` | All fields except K |
-| `Record<K, V>` | Map-like object |
-| `Awaited<P>` | Unwrap Promise |
-| `ReturnType<F>` | The return type of a function |
-| `Parameters<F>` | Tuple of function params |
-| `NonNullable<T>` | Exclude null / undefined |
-
-```ts
-type User = { id: string; email: string; password: string };
-type PublicUser = Omit<User, 'password'>;
-type UserUpdate = Partial<Pick<User, 'email' | 'password'>>;
-```
-
-## Branded types
-
-Prevent string / number mix-ups at compile time.
-
-```ts
-type Brand<K, T> = K & { __brand: T };
-
-type UserId = Brand<string, 'UserId'>;
-type OrgId  = Brand<string, 'OrgId'>;
-
-function userId(s: string): UserId { return s as UserId; }
-function orgId(s: string): OrgId   { return s as OrgId; }
-
-function findUser(id: UserId): User { ... }
-
-findUser(userId('u_1'));        // ✅
-findUser('u_1');                 // ❌ not a UserId
-findUser(orgId('o_1'));          // ❌ wrong brand
-```
-
-The runtime cost is zero — it's just a compile-time distinction. Use it for domain ids, units, hashed vs raw strings.
-
-## Type guards
-
-Custom predicates that narrow.
-
-```ts
-function isUser(x: unknown): x is User {
-  return typeof x === 'object' && x !== null && 'id' in x && typeof (x as any).id === 'string';
-}
-
-const raw: unknown = fetchSomething();
-if (isUser(raw)) {
-  raw.id.toLowerCase();          // raw is narrowed to User
-}
-```
-
-For anything more than two fields, use a schema validator (`zod`, `valibot`). Hand-written guards drift from the shape.
-
-## `as const` — literal-typed values
-
-Widening turns `"hello"` into `string`. `as const` keeps it literal.
-
-```ts
-const ROLES = ['admin', 'user', 'guest'] as const;
-type Role = typeof ROLES[number];    // 'admin' | 'user' | 'guest'
-
-const CONFIG = { retries: 3, timeout: 5000 } as const;
-// CONFIG.retries is 3, not number; CONFIG is readonly
-```
-
-## Conditional & mapped types — use sparingly
-
-Powerful, but expensive on the reader. Reach for them when the alternative is copy-paste.
-
-```ts
-// Conditional
-type NonNull<T> = T extends null | undefined ? never : T;
-
-// Mapped
-type Nullable<T> = { [K in keyof T]: T[K] | null };
-
-// Both, with `infer`
-type UnwrapArray<T> = T extends (infer U)[] ? U : T;
-
-type X = UnwrapArray<User[]>;        // User
-type Y = UnwrapArray<string>;        // string
-```
-
-If the type gets fancy enough that a teammate asks "what does this do?", add a comment with an example, or simplify.
-
-## `never` — the bottom type
-
-`never` appears when TS knows no value can reach here.
-
-```ts
-function throwErr(m: string): never { throw new Error(m); }
-
-const x = cond ? 1 : throwErr('no');   // x is number
-
-// Exhaustiveness (see above)
-default: return assertNever(r);
-```
-
-`never` in a position where you expect a value is a bug signal: "you forgot a case".
-
-## `satisfies` — typecheck without widening
-
-Force a value to conform to a type, but keep its narrow inferred type.
-
-```ts
-const routes = {
-  home: '/home',
-  profile: '/profile/:id',
-} satisfies Record<string, string>;
-
-// routes.home is the literal "/home", not string
-type RouteKey = keyof typeof routes;    // 'home' | 'profile'
-```
-
-Great for config objects. `as Record<string, string>` would erase the literals.
-
-## Enums — avoid; prefer string unions
-
-```ts
-// ❌ enum (generates runtime code, not tree-shakeable, weird reverse mapping)
-enum Role { Admin, User, Guest }
-
-// ✅ string union (zero runtime, tree-shakeable, grepable)
-type Role = 'admin' | 'user' | 'guest';
-
-// ✅ object + `as const` if you need a value container
-const Role = { Admin: 'admin', User: 'user', Guest: 'guest' } as const;
-type Role = typeof Role[keyof typeof Role];
-```
-
-`const enum` exists but trips up bundlers and project-references. Not worth it.
-
-## Class vs. type vs. interface
-
-| Use | When |
-|---|---|
-| `type` | Unions, intersections, mapped / conditional, brands, non-extensible shapes |
-| `interface` | Public object contract, open for extension by users (declaration merging) |
-| `class` | Need a runtime object with methods and state |
-
-Prefer `type` for data and `interface` for object behaviours. Don't mix conventions arbitrarily.