@booklib/skills 1.5.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@booklib/skills",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Book knowledge distilled into structured AI skills for Claude Code and other AI assistants",
   "bin": {
     "skills": "bin/skills.js"

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

@@ -29,6 +29,7 @@
         "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/scripts/review.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+review.py — Pre-analysis script for Effective TypeScript reviews.
+Usage: python review.py <file.ts|file.tsx>
+
+Scans a TypeScript source file for anti-patterns from the book's 62 items:
+any usage, type assertions, object wrapper types, non-null assertions,
+missing strict mode, interface-of-unions, plain string types, and more.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+CHECKS = [
+    (
+        r":\s*any\b",
+        "Item 5/38: any type annotation",
+        "replace with a specific type, generic parameter, or unknown for truly unknown values",
+    ),
+    (
+        r"\bas\s+any\b",
+        "Item 38/40: 'as any' assertion",
+        "scope 'as any' as narrowly as possible — hide inside a well-typed wrapper function; prefer 'as unknown as T' for safer double assertion",
+    ),
+    (
+        r"\bString\b|\bNumber\b|\bBoolean\b|\bObject\b|\bSymbol\b",
+        "Item 10: Object wrapper type (String/Number/Boolean)",
+        "use primitive types: string, number, boolean — never the wrapper class types",
+    ),
+    (
+        r"!\.",
+        "Item 28/31: Non-null assertion (!).",
+        "non-null assertions are usually a symptom of an imprecise type — fix the type instead; consider optional chaining (?.) or a type guard",
+    ),
+    (
+        r"@ts-ignore|@ts-nocheck",
+        "Item 38: @ts-ignore suppresses type errors",
+        "fix the underlying type issue; if unavoidable use @ts-expect-error with a comment explaining why",
+    ),
+    (
+        r"function\s+\w+[^{]*\{[^}]{0,20}\}",
+        None,  # skip — too noisy
+        None,
+    ),
+    (
+        r"interface\s+\w+\s*\{[^}]*\?[^}]*\?[^}]*\}",
+        "Item 32: Interface with multiple optional fields",
+        "multiple optional fields that have implicit relationships suggest an interface-of-unions — convert to a tagged discriminated union",
+    ),
+    (
+        r"param(?:eter)?\s*:\s*string(?!\s*[|&])",
+        "Item 33: Plain string parameter",
+        "consider a string literal union if the parameter has a finite set of valid values (e.g. 'asc' | 'desc')",
+    ),
+    (
+        r"\.json\(\)\s*as\s+\w",
+        "Item 9/40: Direct type assertion on .json()",
+        "assign to unknown first, then narrow: 'const raw: unknown = await res.json()' — assertion inside a well-typed wrapper is acceptable (Item 40)",
+    ),
+    (
+        r"Promise<any>",
+        "Item 38: Promise<any> return type",
+        "replace with Promise<unknown> or a concrete type — Promise<any> disables type checking on the resolved value",
+    ),
+]
+
+
+def scan(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("//") or stripped.startswith("*"):
+            continue
+        for pattern, label, advice in CHECKS:
+            if label is None:
+                continue
+            if re.search(pattern, line):
+                findings.append({
+                    "line": lineno,
+                    "text": line.rstrip(),
+                    "label": label,
+                    "advice": advice,
+                })
+    return findings
+
+
+def check_strict(source: str) -> bool:
+    """Returns True if this looks like a tsconfig with strict mode enabled."""
+    return bool(re.search(r'"strict"\s*:\s*true', source))
+
+
+def sep(char="-", width=70) -> str:
+    return char * width
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python review.py <file.ts|file.tsx>")
+        sys.exit(1)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    if path.suffix.lower() not in (".ts", ".tsx", ".json"):
+        print(f"Warning: expected .ts/.tsx, got '{path.suffix}' — continuing anyway")
+
+    source = path.read_text(encoding="utf-8", errors="replace")
+
+    # Special case: tsconfig.json
+    if path.name == "tsconfig.json":
+        print(sep("="))
+        print("EFFECTIVE TYPESCRIPT — TSCONFIG CHECK")
+        print(sep("="))
+        if check_strict(source):
+            print("  [OK] strict: true is enabled (Item 2)")
+        else:
+            print("  [!] strict: true is NOT enabled — Item 2: always enable strict mode")
+            print("       Add: \"strict\": true to compilerOptions")
+        print()
+        print(sep("="))
+        return
+
+    findings = scan(source)
+    groups: dict[str, list] = {}
+    for f in findings:
+        groups.setdefault(f["label"], []).append(f)
+
+    print(sep("="))
+    print("EFFECTIVE TYPESCRIPT — PRE-REVIEW REPORT")
+    print(sep("="))
+    print(f"File   : {path}")
+    print(f"Lines  : {len(source.splitlines())}")
+    print(f"Issues : {len(findings)} potential violations across {len(groups)} categories")
+    print()
+
+    if not findings:
+        print("  [OK] No common Effective TypeScript anti-patterns detected.")
+        print()
+    else:
+        for label, items in groups.items():
+            print(sep())
+            print(f"  {label}  ({len(items)} occurrence{'s' if len(items) != 1 else ''})")
+            print(sep())
+            print(f"  Advice: {items[0]['advice']}")
+            print()
+            for item in items[:5]:
+                print(f"  line {item['line']:>4}:  {item['text'][:100]}")
+            if len(items) > 5:
+                print(f"  ... and {len(items) - 5} more")
+            print()
+
+    severity = (
+        "HIGH" if len(findings) >= 5
+        else "MEDIUM" if len(findings) >= 2
+        else "LOW" if findings
+        else "NONE"
+    )
+    print(sep("="))
+    print(f"SEVERITY: {severity}  |  Key items: Item 2 (strict), Item 5/38 (any/unknown), Item 9 (assertions), Item 28/32 (tagged unions), Item 33 (literal types)")
+    print(sep("="))
+
+
+if __name__ == "__main__":
+    main()

package/skills/programming-with-rust/scripts/review.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+review.py — Pre-analysis script for Programming with Rust reviews.
+Usage: python review.py <file.rs>
+
+Scans a Rust source file for anti-patterns from the book:
+unwrap misuse, unnecessary cloning, unsafe shared state, manual index loops,
+missing Result return types, static mut, and more.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+CHECKS = [
+    (
+        r"\.unwrap\(\)",
+        "Ch 12: .unwrap()",
+        "panics on failure in production paths — use ?, .expect(\"reason\"), or match",
+    ),
+    (
+        r"\.clone\(\)",
+        "Ch 8: .clone()",
+        "verify cloning is necessary — prefer borrowing (&T or &mut T) to avoid heap allocation",
+    ),
+    (
+        r"static\s+mut\s+\w+",
+        "Ch 19: static mut",
+        "data race risk — replace with Arc<Mutex<T>> or std::sync::atomic types",
+    ),
+    (
+        r"unsafe\s*\{",
+        "Ch 20: unsafe block",
+        "minimize unsafe scope; add a // SAFETY: comment explaining the invariant being upheld",
+    ),
+    (
+        r"for\s+\w+\s+in\s+0\s*\.\.\s*\w+\.len\(\)",
+        "Ch 6: Manual index loop",
+        "use iterator adapters: for item in &collection, or .iter().enumerate() if index is needed",
+    ),
+    (
+        r"\bpanic!\s*\(",
+        "Ch 12: panic!()",
+        "panics should be reserved for unrecoverable programmer errors — use Result<T, E> for recoverable failures",
+    ),
+    (
+        r"Box<dyn\s+\w+>",
+        "Ch 17: dyn Trait (dynamic dispatch)",
+        "prefer impl Trait for static dispatch (zero-cost) unless you need a heterogeneous collection",
+    ),
+    (
+        r"Rc\s*::\s*(new|clone)\b",
+        "Ch 19: Rc usage",
+        "Rc is not Send — if shared across threads, use Arc instead",
+    ),
+    (
+        r"\.expect\s*\(\s*\)",
+        "Ch 12: .expect() with empty string",
+        "add a meaningful reason: .expect(\"invariant: config is always loaded before this point\")",
+    ),
+]
+
+
+def scan(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("//"):
+            continue
+        for pattern, label, advice in CHECKS:
+            if re.search(pattern, line):
+                findings.append({
+                    "line": lineno,
+                    "text": line.rstrip(),
+                    "label": label,
+                    "advice": advice,
+                })
+    return findings
+
+
+def sep(char="-", width=70) -> str:
+    return char * width
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python review.py <file.rs>")
+        sys.exit(1)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    if path.suffix.lower() != ".rs":
+        print(f"Warning: expected a .rs file, got '{path.suffix}' — continuing anyway")
+
+    source = path.read_text(encoding="utf-8", errors="replace")
+    findings = scan(source)
+    groups: dict[str, list] = {}
+    for f in findings:
+        groups.setdefault(f["label"], []).append(f)
+
+    print(sep("="))
+    print("PROGRAMMING WITH RUST — PRE-REVIEW REPORT")
+    print(sep("="))
+    print(f"File   : {path}")
+    print(f"Lines  : {len(source.splitlines())}")
+    print(f"Issues : {len(findings)} potential anti-patterns across {len(groups)} categories")
+    print()
+
+    if not findings:
+        print("  [OK] No common Rust anti-patterns detected.")
+        print()
+    else:
+        for label, items in groups.items():
+            print(sep())
+            print(f"  {label}  ({len(items)} occurrence{'s' if len(items) != 1 else ''})")
+            print(sep())
+            print(f"  Advice: {items[0]['advice']}")
+            print()
+            for item in items[:5]:
+                print(f"  line {item['line']:>4}:  {item['text'][:100]}")
+            if len(items) > 5:
+                print(f"  ... and {len(items) - 5} more")
+            print()
+
+    severity = (
+        "HIGH" if len(findings) >= 5
+        else "MEDIUM" if len(findings) >= 2
+        else "LOW" if findings
+        else "NONE"
+    )
+    print(sep("="))
+    print(f"SEVERITY: {severity}  |  Key chapters: Ch 8 (ownership), Ch 12 (errors), Ch 17 (traits), Ch 19 (concurrency), Ch 20 (memory)")
+    print(sep("="))
+
+
+if __name__ == "__main__":
+    main()