@booklib/core 2.0.0

package/skills/effective-python/scripts/lint.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+lint.py — Ruff linter tuned to Effective Python items.
+Usage: python lint.py <path>
+
+Runs ruff with rules that map directly to Effective Python advice,
+then annotates each violation with the relevant item number and title.
+"""
+
+import json
+import subprocess
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+
+# Maps ruff rule code prefixes/exact codes -> (Item number, short description)
+RULE_TO_ITEM = {
+    "E711": ("Item 2",  "PEP 8: use 'is None' / 'is not None', not == None"),
+    "E712": ("Item 2",  "PEP 8: use 'is True' / 'is False', not == True/False"),
+    "B006": ("Item 24", "Avoid mutable default arguments"),
+    "B007": ("Item 7",  "Unused loop variable — use _ for throwaway"),
+    "B008": ("Item 24", "Do not call mutable objects as default arguments"),
+    "C400": ("Item 27", "Rewrite map() as a list comprehension"),
+    "C401": ("Item 27", "Rewrite set() with a comprehension"),
+    "C402": ("Item 27", "Rewrite dict() with a dict comprehension"),
+    "C403": ("Item 27", "Rewrite list() with a list comprehension"),
+    "C404": ("Item 27", "Rewrite list of tuples as dict comprehension"),
+    "C405": ("Item 27", "Rewrite set literal — unnecessary literal call"),
+    "C406": ("Item 27", "Rewrite dict literal — unnecessary literal call"),
+    "C408": ("Item 27", "Rewrite dict()/list()/tuple() with literal"),
+    "C409": ("Item 28", "Unnecessary literal in tuple()"),
+    "C410": ("Item 28", "Unnecessary literal in list()"),
+    "C411": ("Item 27", "Unnecessary list() call"),
+    "C413": ("Item 27", "Unnecessary list/reversed() around sorted()"),
+    "C414": ("Item 27", "Unnecessary double cast in comprehension"),
+    "C415": ("Item 29", "Unnecessary subscript reversal in comprehension"),
+    "C416": ("Item 27", "Unnecessary list comprehension — use list()"),
+    "C417": ("Item 27", "Unnecessary map() — use generator/comprehension"),
+    "SIM101": ("Item 7",  "Merge duplicate isinstance() checks with tuple"),
+    "SIM102": ("Item 7",  "Collapse nested if into single if"),
+    "SIM103": ("Item 7",  "Return condition directly, not if/else True/False"),
+    "SIM105": ("Item 35", "Use contextlib.suppress instead of try/except/pass"),
+    "SIM108": ("Item 7",  "Use ternary operator instead of if/else block"),
+    "SIM110": ("Item 27", "Use comprehension instead of for-loop with append"),
+    "SIM115": ("Item 66", "Use context manager for open()"),
+    "SIM117": ("Item 66", "Merge nested with statements"),
+    "UP001": ("Item 2",  "pyupgrade: use modern Python syntax"),
+    "UP003": ("Item 2",  "pyupgrade: use type() instead of deprecated form"),
+    "UP006": ("Item 90", "Use 'list' instead of 'List' for type hints (3.9+)"),
+    "UP007": ("Item 90", "Use 'X | Y' instead of 'Optional[X]' (3.10+)"),
+    "UP008": ("Item 90", "Use 'super()' without arguments"),
+    "UP009": ("Item 2",  "pyupgrade: UTF-8 encoding declaration unnecessary"),
+    "UP010": ("Item 2",  "pyupgrade: unnecessary __future__ import"),
+    "UP032": ("Item 4",  "Use f-string instead of .format()"),
+    "UP034": ("Item 2",  "pyupgrade: extraneous parentheses"),
+}
+
+RUFF_CONFIG = textwrap.dedent("""\
+    [lint]
+    select = [
+        "E711", "E712",
+        "B006", "B007", "B008",
+        "C4",
+        "SIM",
+        "UP",
+    ]
+    ignore = []
+""")
+
+
+def find_item(code: str):
+    if code in RULE_TO_ITEM:
+        return RULE_TO_ITEM[code]
+    # Try prefix match (e.g. SIM, UP, C4xx)
+    for prefix_len in (5, 4, 3, 2):
+        prefix = code[:prefix_len]
+        if prefix in RULE_TO_ITEM:
+            return RULE_TO_ITEM[prefix]
+    return None
+
+
+def run_ruff(target: Path, config_path: Path):
+    cmd = [
+        "ruff", "check",
+        "--config", str(config_path),
+        "--output-format", "json",
+        str(target),
+    ]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        return result.stdout, result.stderr, result.returncode
+    except FileNotFoundError:
+        return None, "NOT_FOUND", 1
+    except subprocess.TimeoutExpired:
+        return None, "TIMEOUT", 1
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python lint.py <path>")
+        sys.exit(1)
+
+    target = Path(sys.argv[1])
+    if not target.exists():
+        print(f"Error: path not found: {target}")
+        sys.exit(1)
+
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".toml", prefix="ruff_ep_", delete=False
+    ) as tmp:
+        tmp.write(RUFF_CONFIG)
+        config_path = Path(tmp.name)
+
+    try:
+        stdout, stderr, returncode = run_ruff(target, config_path)
+    finally:
+        config_path.unlink(missing_ok=True)
+
+    if stdout is None:
+        if stderr == "NOT_FOUND":
+            print("Error: ruff is not installed.")
+            print("Install it with:  pip install ruff")
+            print("Or globally:      pipx install ruff")
+        elif stderr == "TIMEOUT":
+            print("Error: ruff timed out.")
+        else:
+            print(f"Error running ruff: {stderr}")
+        sys.exit(1)
+
+    print(f"Effective Python lint report — {target}")
+    print("-" * 70)
+
+    try:
+        violations = json.loads(stdout) if stdout.strip() else []
+    except json.JSONDecodeError:
+        print("Raw ruff output:")
+        print(stdout)
+        sys.exit(returncode)
+
+    if not violations:
+        print("No violations found. Code aligns well with Effective Python.")
+        sys.exit(0)
+
+    # Group by item
+    by_item: dict[str, list] = {}
+    for v in violations:
+        code = v.get("code", "?")
+        mapping = find_item(code)
+        item_key = mapping[0] if mapping else "Other"
+        by_item.setdefault(item_key, []).append((v, mapping))
+
+    total = 0
+    for item_key in sorted(by_item):
+        entries = by_item[item_key]
+        item_desc = entries[0][1][1] if entries[0][1] else "ruff violation"
+        print(f"\n[{item_key}] {item_desc}")
+        for v, _ in entries:
+            loc = v.get("location", {})
+            row, col = loc.get("row", "?"), loc.get("column", "?")
+            filename = Path(v.get("filename", str(target))).name
+            message = v.get("message", "")
+            code = v.get("code", "?")
+            print(f"  {filename}:{row}:{col}  [{code}] {message}")
+            total += 1
+
+    print(f"\n{'-' * 70}")
+    print(f"Total violations: {total}")
+    sys.exit(1 if violations else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/effective-typescript/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: effective-typescript
+version: "1.0"
+license: MIT
+tags: [typescript, javascript, types]
+description: >
+  Review existing TypeScript code and write new TypeScript following the 62 items from
+  "Effective TypeScript" by Dan Vanderkam. Use when writing TypeScript, reviewing TypeScript
+  code, working with type design, avoiding any, managing type declarations, or migrating
+  JavaScript to TypeScript. Trigger on: "TypeScript best practices", "type safety", "any",
+  "type assertions", "type design", "strict mode", "TypeScript review", "migrate to TypeScript".
+---
+
+# Effective TypeScript Skill
+
+Apply the 62 items from Dan Vanderkam's "Effective TypeScript" to review existing code and write new TypeScript. This skill operates in two modes: **Review Mode** (analyze code for violations) and **Write Mode** (produce idiomatic, well-typed TypeScript from scratch).
+
+## Reference Files
+
+This skill includes categorized reference files covering all 62 items:
+
+- `ref-01-getting-to-know-ts.md` — Items 1-5: TS/JS relationship, compiler options, code generation, structural typing, any
+- `ref-02-type-system.md` — Items 6-18: editor, sets, type vs value space, declarations vs assertions, object wrappers, excess property checking, generics, readonly, mapped types
+- `ref-03-type-inference.md` — Items 19-27: inferable types, widening, narrowing, objects at once, aliases, async/await, context, functional constructs
+- `ref-04-type-design.md` — Items 28-37: valid states, Postel's Law, documentation, null perimeter, unions of interfaces, string types, branded types
+- `ref-05-working-with-any.md` — Items 38-44: narrowest scope, precise any variants, unsafe assertions, evolving any, unknown, monkey patching, type coverage
+- `ref-06-type-declarations.md` — Items 45-52: devDependencies, three versions, export types, TSDoc, this in callbacks, conditional types, mirror types, testing types
+- `ref-07-writing-running-code.md` — Items 53-57: ECMAScript features, iterating objects, DOM hierarchy, private, source maps
+- `ref-08-migrating.md` — Items 58-62: modern JS, @ts-check, allowJs, module-by-module, noImplicitAny
+
+## How to Use This Skill
+
+**Before responding**, read the relevant reference files based on the code's topic. For a general review, read all files. For targeted work (e.g., type design), read the specific reference (e.g., `ref-04-type-design.md`).
+
+---
+
+## Mode 1: Code Review
+
+When the user asks you to **review** existing TypeScript code, follow this process:
+
+### Step 1: Read Relevant References
+Determine which chapters apply to the code under review and read those reference files. If unsure, read all of them.
+
+### Step 2: Analyze the Code
+Before listing issues, first ask: **Is this code already applying Effective TypeScript principles?** Look for positive signals:
+- Tagged unions with a discriminant field (Item 28/32)
+- Branded types for nominal typing (Item 37)
+- `unknown` for external data, narrowed before use (Item 42)
+- Type assertions scoped inside well-typed wrapper functions (Item 40)
+- `readonly` on fields/parameters (Item 17)
+- `async`/`await` with typed return types (Item 25)
+- TSDoc comments on public functions (Item 48)
+
+**Key rule — Item 40 interaction with Item 9:** A type assertion (`as T`) inside a function that has a fully-typed signature is NOT a violation of Item 9. Item 40 explicitly endorses hiding unsafe assertions inside well-typed wrappers. Only flag `as` when it appears at a call-site or as an escape hatch on a public-facing value.
+
+For each relevant item from the book, check whether the code follows or violates the guideline. Focus on:
+
+1. **TypeScript Fundamentals** (Items 1-5): Is `strict` mode enabled? Is `any` used carelessly? Does structural typing cause surprises?
+2. **Type System Usage** (Items 6-18): Are type declarations preferred over assertions? Are object wrapper types avoided? Are `readonly` and mapped types used appropriately?
+3. **Type Inference** (Items 19-27): Is inference relied upon where possible? Are `async`/`await` used over callbacks? Are aliases consistent?
+4. **Type Design** (Items 28-37): Do types represent only valid states? Are string types replaced with literal unions? Are null values pushed to the perimeter?
+5. **Working with any** (Items 38-44): Is `any` scoped as narrowly as possible? Is `unknown` used for truly unknown values? Are unsafe assertions hidden in well-typed wrappers?
+6. **Type Declarations** (Items 45-52): Are `@types` in devDependencies? Are public API types exported? Is TSDoc used for comments?
+7. **Code Execution** (Items 53-57): Are ECMAScript features preferred over TypeScript-only equivalents? Is object iteration done safely?
+8. **Migration** (Items 58-62): Is modern JavaScript used as a baseline? Is migration done module-by-module?
+
+### Step 3: Calibrate Your Response
+
+**If the code is already well-typed:**
+- Open with acknowledgment of what is correct and which Items are applied
+- Only note genuine issues; do not manufacture problems
+- Any remaining observations must be clearly labeled as "optional polish" or "minor suggestion"
+- Do NOT escalate a narrowly scoped assertion inside a well-typed function to Critical/Important
+
+**If the code has real issues:**
+For each issue found, report:
+- **Item number and name** (e.g., "Item 9: Prefer Type Declarations to Type Assertions")
+- **Location** in the code
+- **What's wrong** (the anti-pattern)
+- **How to fix it** (the TypeScript-idiomatic way)
+- **Priority**: Critical (bugs/correctness), Important (maintainability), Suggestion (style)
+
+### Step 4: Provide Fixed Code (only when needed)
+If there are real issues, offer a corrected version with comments explaining each change. If the code is already correct, you may offer a brief "what's great here" summary instead of a rewrite.
+
+---
+
+## Mode 2: Writing New Code
+
+When the user asks you to **write** new TypeScript code, apply these core practices:
+
+<core_principles>
+
+### Always Apply These Core Practices
+
+1. **Enable strict mode** (Item 2). Never write TypeScript without `"strict": true` in tsconfig.json.
+
+2. **Prefer type declarations over assertions** (Item 9). Use `const x: MyType = value` not `const x = value as MyType`.
+
+3. **Avoid object wrapper types** (Item 10). Use `string`, `number`, `boolean` — never `String`, `Number`, `Boolean`.
+
+4. **Use types that represent only valid states** (Item 28). Eliminate impossible states at the type level with tagged unions.
+
+5. **Push null to the perimeter** (Item 31). Don't scatter `T | null` throughout — handle nullability at boundaries.
+
+6. **Prefer unions of interfaces to interfaces of unions** (Item 32). Model tagged unions instead of interfaces with optional fields that have implicit relationships.
+
+7. **Replace plain string types with string literal unions** (Item 33). `type Direction = 'north' | 'south' | 'east' | 'west'` not `string`.
+
+8. **Generate types from APIs and specs, not data** (Item 35). Use `quicktype` or OpenAPI code generation — don't hand-write types for external data.
+
+9. **Use `unknown` instead of `any` for values with unknown type** (Item 42). `unknown` forces callers to narrow before use.
+
+10. **Scope `any` as narrowly as possible** (Item 38). Apply it to a single value, never a whole object or module.
+
+11. **Use `readonly` to prevent mutation bugs** (Item 17). Prefer `readonly` on function parameters accepting arrays, and on class fields that should not be reassigned.
+
+12. **Use `async`/`await` over raw Promises and callbacks** (Item 25). It produces cleaner inferred types and clearer code.
+
+13. **Use type aliases to avoid repeating yourself** (Item 14). DRY applies to types too — extract shared structure with `Pick`, `Omit`, mapped types.
+
+14. **Export all types that appear in public APIs** (Item 47). Don't force users to reconstruct types with `ReturnType<>` or `Parameters<>`.
+
+15. **Use TSDoc for API comments** (Item 48). `/** */` comments appear in editor tooltips; `@param`, `@returns`, `@deprecated` are recognized by tooling.
+
+</core_principles>
+
+<examples>
+
+### Type Structure Template
+
+<example id="1" title="Core type patterns — branded types, tagged unions, unknown, async/await">
+
+```typescript
+// Prefer interfaces for object shapes (extendable); type aliases for unions/intersections
+interface User {
+  readonly id: UserId;     // Item 17: readonly on fields that shouldn't change
+  name: string;
+  email: string;
+}
+
+// Branded type for nominal typing (Item 37)
+type UserId = string & { readonly __brand: 'UserId' };
+
+// Tagged union — only valid states representable (Item 28, 32)
+type RequestState<T> =
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; message: string };
+
+// unknown, not any, for values from external sources (Item 42)
+function parseResponse(json: string): unknown {
+  return JSON.parse(json);
+}
+
+// async/await over callbacks (Item 25)
+async function fetchUser(id: UserId): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as User; // narrowly scoped assertion inside well-typed function (Item 40)
+}
+```
+
+</example>
+
+</examples>
+
+<guidelines>
+
+### any Guidelines
+- If `any` is unavoidable, apply it to the smallest possible scope (Item 38)
+- Prefer `unknown` for values received from external sources (Item 42)
+- Hide unsafe assertions inside well-typed wrapper functions (Item 40)
+- Track type coverage with `type-coverage` CLI to prevent regressions (Item 44)
+
+</guidelines>
+
+---
+
+## Priority of Items by Impact
+
+<core_principles>
+
+### Critical (Correctness & Bugs)
+- Item 2: Enable `strict` mode — `noImplicitAny` and `strictNullChecks` prevent whole classes of bugs
+- Item 9: Prefer declarations to assertions — **but see Item 40**: assertions inside well-typed wrappers are fine
+- Item 28: Types that always represent valid states — impossible states cause runtime errors
+- Item 31: Push null to the perimeter — scattered nullability causes null dereferences
+- Item 42: Use `unknown` instead of `any` — `any` silently disables type checking
+
+> **Item 40 exception:** `raw as SomeType` inside a function with a fully-typed signature is explicitly endorsed by Item 40. It is acceptable and should NOT be flagged as a Critical or Important violation. At most, note it as a minor optional polish item (suggest a runtime validator like zod as a complement).
+
+</core_principles>
+
+<guidelines>
+
+### Important (Maintainability)
+- Item 13: Know the differences between `type` and `interface`
+- Item 14: Use type operations and generics to avoid repetition
+- Item 17: Use `readonly` to prevent mutation bugs
+- Item 25: Use `async`/`await` over callbacks
+- Item 32: Prefer unions of interfaces to interfaces of unions
+- Item 33: Prefer string literal unions over plain `string`
+- Item 47: Export all types that appear in public APIs
+- Item 48: Use TSDoc for API comments
+
+### Suggestions (Polish & Optimization)
+- Item 19: Omit inferable types to reduce clutter
+- Item 35: Generate types from APIs and specs
+- Item 37: Consider brands for nominal typing
+- Item 44: Track type coverage
+- Item 53: Prefer ECMAScript features over TypeScript-only equivalents
+
+</guidelines>
+
+<anti_patterns>
+
+## Common Anti-Patterns to Flag
+
+### any overuse (Items 38, 42)
+- Return type `Promise<any>` — use `Promise<unknown>` or a concrete typed interface
+- `as any` cast at call-site or on a public-facing value — narrowest-scope rule violated
+- Interface fields typed as `any` (e.g., `result?: any`) — use `unknown` or a typed union
+
+### Interface of unions (Items 28, 32)
+- An interface with `boolean` + optional fields that only make sense together: `{ isLoading: boolean; data?: T; error?: string }` is an interface-of-unions anti-pattern
+  - Invalid combinations are representable (e.g., `{ isLoading: true, data: [...] }` or `{ isLoading: false, data: undefined }`)
+  - Fix: replace with a tagged union using a `status` discriminant field
+  - Non-null assertions (`!`) inside render/display logic are a strong symptom of this pattern
+
+### Plain string parameters (Item 33)
+- Function parameters typed as `string` when only a small, known set of values is valid
+  - Fix: `type Theme = 'light' | 'dark'` or similar literal union
+
+### Type assertions at call-sites (Item 9)
+- `value as SomeType` appearing in application code (not inside a well-typed wrapper function)
+  - Fix: use a type declaration `const x: SomeType = value` or a validator function that returns the typed value
+
+### Missing strict mode (Item 2)
+- TypeScript files without `"strict": true` in tsconfig — whole classes of bugs (null dereferences, implicit any) go undetected
+
+### Callbacks over async/await (Item 25)
+- `.then()` chains instead of `async`/`await` — harder to read, worse type inference
+
+</anti_patterns>
+
+<strengths_to_praise>
+
+## Strengths to Recognize in Good Code
+
+When reviewing code that applies these patterns correctly, explicitly acknowledge:
+
+- **Branded types** (Item 37): `type FooId = string & { readonly __brand: 'FooId' }` — prevents mixing up identifiers of different domain entities
+- **Tagged/discriminated unions** (Item 28, 32): `type Result = { status: 'success'; data: T } | { status: 'error'; message: string }` — only valid states representable
+- **`unknown` for external data** (Item 42): `const raw: unknown = await response.json()` — forces explicit narrowing before use
+- **Assertion inside well-typed wrapper** (Item 40): `as T` inside a function with a fully-typed signature — safe encapsulation of unsafe boundary
+- **`readonly` fields** (Item 17): `readonly id: UserId` on domain entity interfaces — communicates immutability intent
+- **`async`/`await`** (Item 25): cleaner than `.then()` chains, better type inference
+- **TSDoc on public functions** (Item 48): `/** @param ... @returns ... */` — shows up in editor tooltips
+- **String literal unions** (Item 33): `type Status = 'pending' | 'processing' | 'shipped'` instead of `string`
+
+</strengths_to_praise>

package/skills/effective-typescript/audit.json

@@ -0,0 +1,29 @@
+{
+  "name": "Effective TypeScript Static Checks",
+  "rules": [
+    {
+      "id": "Item 5",
+      "pattern": ":\\s*any\\b",
+      "message": "Found 'any' type annotation. Replace with specific type or 'unknown' (Item 5/38).",
+      "severity": "🔴 Critical"
+    },
+    {
+      "id": "Item 28",
+      "pattern": "!\\.",
+      "message": "Found non-null assertion (!). Fix the type or use optional chaining (?.) (Item 28/31).",
+      "severity": "🔴 Critical"
+    },
+    {
+      "id": "Item 38",
+      "pattern": "@ts-ignore|@ts-nocheck",
+      "message": "Found @ts-ignore. Fix the underlying type issue (Item 38).",
+      "severity": "🔴 Critical"
+    },
+    {
+      "id": "Item 10",
+      "pattern": "\\b(String|Number|Boolean)\\b",
+      "message": "Found object wrapper type. Use primitive types (string, number, boolean) instead (Item 10).",
+      "severity": "🟡 Improvement"
+    }
+  ]
+}

package/skills/effective-typescript/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-any-assertions-string-types",
+      "prompt": "Review this TypeScript code:\n\n```typescript\nasync function loadConfig(env: string): Promise<any> {\n  const res = await fetch(`/config/${env}`);\n  const data = res.json() as any;\n  return data;\n}\n\ninterface AppState {\n  loading: boolean;\n  result?: any;\n  error?: string;\n}\n\nfunction applyTheme(theme: string) {\n  document.body.className = theme;\n}\n```",
+      "expectations": [
+        "Flag Item 42: return type should be unknown or a typed interface, not any",
+        "Flag Item 9: res.json() as any is a type assertion — prefer a type declaration or typed wrapper",
+        "Flag Item 28/32: AppState is an interface of unions — loading:true with result/error present is representable; suggest a tagged union instead",
+        "Flag Item 33: theme parameter should be a string literal union (e.g. 'light' | 'dark'), not plain string",
+        "Provide a fixed version using unknown, a tagged union, and a literal union type"
+      ]
+    },
+    {
+      "id": "eval-02-subtle-interface-of-unions",
+      "prompt": "Review this TypeScript code:\n\n```typescript\ninterface FetchState {\n  isLoading: boolean;\n  data?: User[];\n  errorMessage?: string;\n  lastUpdated?: Date;\n}\n\nfunction render(state: FetchState) {\n  if (state.isLoading) {\n    showSpinner();\n  } else if (state.errorMessage) {\n    showError(state.errorMessage);\n  } else {\n    showData(state.data!); // non-null assertion\n  }\n}\n```",
+      "expectations": [
+        "Flag Item 32: FetchState is an interface of unions — data and errorMessage have an implicit relationship that the type doesn't enforce",
+        "Flag Item 28: states like { isLoading: false, data: [...], errorMessage: 'oops' } are representable but invalid",
+        "Flag the non-null assertion (!) on state.data — it's a symptom of the type not representing valid states",
+        "Suggest a tagged union: type FetchState = { status: 'loading' } | { status: 'success'; data: User[]; lastUpdated: Date } | { status: 'error'; message: string }",
+        "Show how the fixed type makes the render function exhaustive and removes the need for the non-null assertion"
+      ]
+    },
+    {
+      "id": "eval-03-already-well-typed",
+      "prompt": "Review this TypeScript code:\n\n```typescript\ntype OrderId = string & { readonly __brand: 'OrderId' };\n\ntype OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';\n\ntype OrderResult =\n  | { status: 'success'; order: Order }\n  | { status: 'not_found' }\n  | { status: 'error'; message: string };\n\ninterface Order {\n  readonly id: OrderId;\n  readonly customerId: string;\n  status: OrderStatus;\n  items: readonly OrderItem[];\n}\n\n/**\n * Fetches an order by ID.\n * @param id - The branded order identifier\n * @returns The order result discriminated union\n */\nasync function fetchOrder(id: OrderId): Promise<OrderResult> {\n  const response = await fetch(`/api/orders/${id}`);\n  if (response.status === 404) return { status: 'not_found' };\n  if (!response.ok) return { status: 'error', message: `HTTP ${response.status}` };\n  const raw: unknown = await response.json();\n  return { status: 'success', order: raw as Order };\n}\n```",
+      "expectations": [
+        "Recognize that this code is already applying Effective TypeScript principles correctly",
+        "Acknowledge Item 37 (branded OrderId), Item 33 (OrderStatus literal union), Item 28/32 (tagged union OrderResult), Item 17 (readonly fields), Item 42 (unknown from JSON), Item 40 (assertion inside well-typed function), Item 25 (async/await), Item 48 (TSDoc)",
+        "Do NOT manufacture issues — the code is well-typed",
+        "At most note: raw as Order on the last line is a narrowly scoped assertion (Item 40) — acceptable inside a well-typed wrapper, but mention that a runtime validator (e.g. zod) would catch malformed API responses that TypeScript cannot",
+        "At most offer minor suggestions, clearly marked as optional polish"
+      ]
+    }
+  ]
+}

package/skills/effective-typescript/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 1,
+  "passed": 15,
+  "total": 15,
+  "baseline_pass_rate": 0.333,
+  "baseline_passed": 5,
+  "baseline_total": 15,
+  "delta": 0.667,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-29",
+  "non_standard_provider": true
+}

package/skills/effective-typescript/examples/after.md

@@ -0,0 +1,70 @@
+# After: Effective TypeScript
+
+The same API client rewritten applying Effective TypeScript principles.
+
+```typescript
+// tsconfig.json has "strict": true (Item 2)
+
+// Extract repeated shape into a named type (Item 14)
+interface User {
+  readonly id: UserId;   // Item 17: readonly on identity fields
+  name: string;
+  email: string;
+  role: 'admin' | 'viewer' | 'editor';  // Item 33: literal union, not plain string
+}
+
+// Branded type prevents passing a raw string where a UserId is expected (Item 37)
+type UserId = string & { readonly __brand: 'UserId' };
+
+// Tagged union — only valid states are representable (Item 28, 32)
+// Impossible: { status: 'loading', data: [...] } or { status: 'success', error: '...' }
+type RequestState<T> =
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; message: string };
+
+// Return unknown from untrusted sources — callers must narrow (Item 42)
+async function getUser(id: UserId): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  const raw: unknown = await response.json();
+  // Unsafe assertion scoped inside well-typed function boundary (Item 40)
+  return raw as User;
+}
+
+// Type declaration, not assertion (Item 9)
+const userIdInput: HTMLInputElement | null = document.getElementById('user-id') as HTMLInputElement | null;
+
+// Null pushed to the perimeter — caller handles it once (Item 31)
+function processUser(user: User): string {
+  return user.name.toUpperCase(); // safe — name: string, not string | null
+}
+
+// String literal union, not plain string (Item 33)
+type Direction = 'north' | 'south' | 'east' | 'west';
+function setDirection(direction: Direction) {
+  // TypeScript rejects "sideways" at compile time
+}
+
+// async/await over callbacks — types flow naturally (Item 25)
+async function fetchProfile(id: UserId): Promise<User> {
+  const response = await fetch(`/api/profiles/${id}`);
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as User;
+}
+
+// Named type used in all three functions — DRY (Item 14)
+function renderAdmin(user: User): void {}
+function updateAdmin(user: User): void {}
+function deleteAdmin(user: User): void {}
+```
+
+**Key improvements:**
+- `strict: true` enables `noImplicitAny` and `strictNullChecks` (Item 2)
+- `RequestState<T>` tagged union eliminates impossible states (Items 28, 32)
+- `UserId` branded type prevents mixing up `string` IDs (Item 37)
+- `role` is a literal union, not `string` (Item 33)
+- `unknown` returned from untrusted JSON; unsafe assertion hidden inside typed boundary (Items 40, 42)
+- `async`/`await` replaces callback (Item 25)
+- `User` interface defined once and reused (Item 14)
+- `readonly` on `id` prevents accidental reassignment (Item 17)

package/skills/effective-typescript/examples/before.md

@@ -0,0 +1,47 @@
+# Before: Effective TypeScript
+
+An API client for a user management service — written without applying Effective TypeScript principles.
+
+```typescript
+// No strict mode, any used freely, type assertions everywhere
+
+async function getUser(id: string): Promise<any> {
+  const response = await fetch(`/api/users/${id}`);
+  const data = await response.json();
+  return data;
+}
+
+function processUser(user: any) {
+  console.log(user.name.toUpperCase()); // no null check, will crash if name is null
+}
+
+// Interface of unions — impossible states are representable
+interface RequestState {
+  loading: boolean;
+  data?: any[];       // present when loading is false AND succeeded
+  error?: string;     // present when loading is false AND failed
+  // What does { loading: false, data: [...], error: "oops" } mean?
+}
+
+// Plain string types instead of literal unions
+function setDirection(direction: string) {
+  // accepts "north", "sideways", "diagonal", anything
+}
+
+// Type assertion instead of declaration
+const userId = document.getElementById('user-id') as HTMLInputElement;
+const value = userId.value as string;
+
+// Callback-based async
+function fetchProfile(id: string, callback: (err: Error | null, data: any) => void) {
+  fetch(`/api/profiles/${id}`)
+    .then(res => res.json())
+    .then(data => callback(null, data))
+    .catch(err => callback(err, null));
+}
+
+// Repeated type shape — DRY violation
+function renderAdmin(user: { id: string; name: string; email: string; role: string }) {}
+function updateAdmin(user: { id: string; name: string; email: string; role: string }) {}
+function deleteAdmin(user: { id: string; name: string; email: string; role: string }) {}
+```