@bovinphang/craft-common 1.0.1 → 2.0.0

package/skills/cc-typescript-project-standard/references/type-safety.md

@@ -0,0 +1,154 @@
+#TypeScript type safety
+
+## Purpose
+
+Establish evolvable type contracts for TypeScript applications, libraries, CLI tools and desktop processes, reducing `any`, assertions, and runtime shape drift.
+
+## Procedure
+
+### 1. First determine the type boundary
+
+Divide types into external input, domain model, UI view model, component props, and tool function API. Don't let backend DTOs, form models, and UI presentation models pretend to be each other.
+
+```ts
+interface UserDto {
+  id: string;
+  display_name: string;
+  status: "ACTIVE" | "DISABLED";
+}
+
+interface UserViewModel {
+  id: string;
+  displayName: string;
+  status: "active" | "disabled";
+}
+
+export function mapUserDto(dto: UserDto): UserViewModel {
+  return {
+    id: dto.id,
+    displayName: dto.display_name,
+    status: dto.status === "ACTIVE" ? "active" : "disabled",
+  };
+}
+```
+
+### 2. Use `unknown` and narrowing to handle untrusted data
+
+External input must be verified before use. Don't use `as` to shut up the compiler.
+
+```ts
+interface ApiErrorBody {
+  message: string;
+}
+
+function isApiErrorBody(value: unknown): value is ApiErrorBody {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "message" in value &&
+    typeof value.message === "string"
+  );
+}
+
+export function getApiErrorMessage(value: unknown): string {
+  return isApiErrorBody(value) ? value.message : "Unexpected error";
+}
+```
+
+### 3. Express state machine using discriminant union
+
+Limited states such as asynchronous status, permission branches, payment status, etc. use discriminant fields to expose new branches during compilation.
+
+```ts
+type Loadable<T> =
+  | { state: "idle" }
+  | { state: "loading" }
+  | { state: "success"; data: T }
+  | { state: "error"; error: Error };
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled state: ${JSON.stringify(value)}`);
+}
+
+export function renderUserState(user: Loadable<{ name: string }>): string {
+  switch (user.state) {
+    case "idle":
+      return "Ready";
+    case "loading":
+      return "Loading";
+    case "success":
+      return user.data.name;
+    case "error":
+      return user.error.message;
+    default:
+      return assertNever(user);
+  }
+}
+```
+
+### 4. Let generics serve callers, not show off their skills
+
+Generics should reduce duplication and keep caller inference clear. When the complex type exceeds the reading cost, the named type will be demolished first.
+
+```ts
+interface SelectOption<TValue extends string | number> {
+  label: string;
+  value: TValue;
+}
+
+interface SelectProps<TValue extends string | number> {
+  value: TValue;
+  options: Array<SelectOption<TValue>>;
+  onChange: (value: TValue) => void;
+}
+
+export function Select<TValue extends string | number>({
+  value,
+  options,
+  onChange,
+}: SelectProps<TValue>) {
+  return (
+    <select value={value} onChange={(event) => onChange(event.target.value as TValue)}>
+      {options.map((option) => (
+        <option key={option.value} value={option.value}>
+          {option.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### 5. Protect public types with type testing
+
+Public tool types, component library types, and SDK types should have lightweight type tests or compile-time assertions.
+
+```ts
+type Equal<TLeft, TRight> =
+  (<T>() => T extends TLeft ? 1 : 2) extends <T>() => T extends TRight ? 1 : 2
+    ? true
+    : false;
+
+type Expect<T extends true> = T;
+
+type UserStatus = UserViewModel["status"];
+type _UserStatusTest = Expect<Equal<UserStatus, "active" | "disabled">>;
+```
+
+## Constraints
+
+- Avoid `any`, unguarded non-null assertions and coercion `as` between unrelated types.
+- Don’t pile large anonymous types on function parameters or JSX props; extract named types to express business meaning.
+- Do not over-design recursive conditional types for simple business; type complexity should serve maintainability.
+- The input and output of the public API must be explicitly annotated, and local variables can be relied upon for inference.
+- Type modeling does not replace runtime validation; external data still requires schema or type guard.
+
+## Expected Output
+
+Produce clear type boundaries, narrowable data models, and necessary type testing and verification commands. The review should list type risks, runtime impacts, recommended modeling methods, and whether special fixes are needed.
+
+## Application workflow boundaries
+
+- Use framework project workflows for component architecture, routing, state ownership, and framework-specific module boundaries.
+- Use API integration when runtime API clients, auth refresh, uploads, realtime behavior, or error mapping go beyond TypeScript type contracts.
+- Use validation fix when the task is to repair concrete lint, typecheck, test, build, or CI failures after TypeScript changes.

package/skills/eval_queries.json

@@ -1,4 +1,52 @@
 {
+  "cc-c-project-standard": {
+    "should_trigger": [
+      "Review or fix C allocation cleanup paths",
+      "Review or fix C library ABI compatibility",
+      "Review or fix C output initialization on failure",
+      "Review or fix C buffer length validation",
+      "Review or fix C integer overflow at allocation",
+      "Review or fix pure C ownership transfer",
+      "Review or fix C header implementation boundaries",
+      "Review or fix C failure injection tests",
+      "Review pure C allocation size and allocator pairing without a C++ migration"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-cpp-project-standard": {
+    "should_trigger": [
+      "Review or fix C++ library RAII ownership",
+      "Review or fix C++ exception guarantees",
+      "Review or fix C++ desktop plugin ABI",
+      "Review or fix C++ partial construction cleanup",
+      "Review or fix C++ callback lifetime",
+      "Review or fix C++ compiler standard preservation",
+      "Review or fix C++ custom deleter pairing",
+      "Review or fix C++ module teardown synchronization",
+      "Review borrowed C++ plugin pointer cleanup while preserving disabled-exception policy"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
   "cc-debug-methodology": {
     "should_trigger": [
       "Vite build error reports Module not found, please help me troubleshoot",
@@ -69,6 +117,198 @@
       "Generate comic avatars and brand boards"
     ]
   },
+  "cc-electron-project-standard": {
+    "should_trigger": [
+      "Validate Electron IPC sender before effects",
+      "Restrict an Electron contextBridge API",
+      "Review Electron main preload renderer contracts",
+      "Enable and verify Electron sandbox boundaries",
+      "Restrict Electron navigation and new windows",
+      "Review Electron secure custom protocol assets",
+      "Check Electron native module ABI packaging",
+      "Own Electron IPC handlers during shutdown",
+      "Review Electron IPC delayed preparation after its window closed"
+    ],
+    "should_not_trigger": [
+      "Implement a Node HTTP API without Electron",
+      "Organize an ordinary Rust library",
+      "Only adjust a Vue CSS color",
+      "Design Tauri capabilities",
+      "Tune a Go worker channel",
+      "Translate a marketing headline",
+      "Review a database isolation level",
+      "Generate a diagram without code changes",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-go-concurrency": {
+    "should_trigger": [
+      "Review or fix Go worker cancellation",
+      "Review or fix Go channel close ownership",
+      "Review or fix Go blocked send after receiver exit",
+      "Review or fix bounded Go goroutines",
+      "Review or fix Go synchronization happens-before",
+      "Review or fix Go concurrent shutdown race",
+      "Review or fix Go queue saturation tests",
+      "Review or fix Go worker completion evidence",
+      "Review blocked Go channel shutdown and completion of both workers"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-go-project-standard": {
+    "should_trigger": [
+      "Review or fix go.work submodule boundaries",
+      "Review or fix Go internal package organization",
+      "Review or fix error wrapping in a Go CLI",
+      "Review or fix Go context ownership in blocking operations",
+      "Review or fix Go resource factory cleanup",
+      "Review or fix Go module import compatibility",
+      "Review or fix targeted Go vet and test commands",
+      "Review or fix Go public interface design",
+      "Review a Go library context and error boundary without adding HTTP layers"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-java-project-standard": {
+    "should_trigger": [
+      "Review or fix Java library public module boundary",
+      "Review or fix Java CLI exception causes",
+      "Review or fix Swing module executor cleanup",
+      "Review or fix JavaFX blocking work ownership",
+      "Review or fix Maven wrapper version preservation",
+      "Review or fix Gradle module dependency boundaries",
+      "Review or fix Java file handle closure",
+      "Review or fix Java library behavior tests",
+      "Review Java library partial initialization and cause without adding a Web framework"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-java-runtime": {
+    "should_trigger": [
+      "Review or fix JVM thread pool queue growth",
+      "Review or fix Java desktop thread contention",
+      "Review or fix bounded JFR evidence",
+      "Review or fix Java GC allocation pressure",
+      "Review or fix Java operation deadline overload",
+      "Review or fix Java controlled heap comparison",
+      "Review or fix Java thread dump sampling",
+      "Review or fix Java runtime recovery thresholds",
+      "Diagnose an owned Java executor that does not terminate after shutdown"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-native-memory-safety": {
+    "should_trigger": [
+      "Review or fix C C++ FFI allocator pairing",
+      "Review or fix Rust native borrowed buffer lifetime",
+      "Review or fix native callback after unload",
+      "Review or fix C partial initialization failure",
+      "Review or fix C++ cross-DLL exception boundary",
+      "Review or fix native repeated close behavior",
+      "Review or fix native concurrent destruction race",
+      "Review or fix address sanitizer reproduction evidence",
+      "Review callback completion before native plugin allocator release and unload"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-python-async": {
+    "should_trigger": [
+      "Review or fix Python task cancellation cleanup",
+      "Review or fix Python blocking client offloading",
+      "Review or fix Python async executor bounds",
+      "Review or fix Python async pool ownership",
+      "Review or fix Python TaskGroup error propagation",
+      "Review or fix Python coroutine shutdown deadline",
+      "Review or fix Python thread lifetime after cancellation",
+      "Review or fix Python async resource acquisition timeout",
+      "Review cancellation of an asyncio waiter while its blocking operation continues"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-python-project-standard": {
+    "should_trigger": [
+      "Review or fix Python CLI package layout",
+      "Review or fix pyproject environment conventions",
+      "Review or fix Python library type boundaries",
+      "Review or fix Python import-time side effects",
+      "Review or fix Python resource context manager",
+      "Review or fix existing Ruff mypy pytest scripts",
+      "Review or fix Python public package imports",
+      "Review or fix Python malformed input behavior",
+      "Remove Python library import-time external initialization and preserve cleanup"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
   "cc-refactoring-core": {
     "should_trigger": [
       "Keep observable behavior unchanged while restructuring this frontend module.",
@@ -91,6 +331,54 @@
       "Add a new responsive dashboard from this Figma design."
     ]
   },
+  "cc-rust-async": {
+    "should_trigger": [
+      "Review or fix Rust future cancellation safety",
+      "Review or fix Tokio partial write cancellation",
+      "Review or fix bounded Rust spawned tasks",
+      "Review or fix Rust JoinHandle shutdown ownership",
+      "Review or fix Rust blocking I/O boundary",
+      "Review or fix Rust async queue backpressure",
+      "Review or fix Rust async resource acquisition cancellation",
+      "Review or fix Rust async timeout recovery",
+      "Review cancellation and joining of existing Rust async tasks after a desktop window closes"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
+  "cc-rust-project-standard": {
+    "should_trigger": [
+      "Review or fix Cargo workspace crate boundaries",
+      "Review or fix Rust MSRV and edition configuration",
+      "Review or fix Rust library borrowing contract",
+      "Review or fix Result propagation in a Rust CLI",
+      "Review or fix public Rust module visibility",
+      "Review or fix Rust library release checks",
+      "Review or fix Rust adapter dependency direction",
+      "Review or fix Rust resource ownership transfer",
+      "Review Rust Result cause and partial acquisition cleanup in a desktop core"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
   "cc-source-driven-development": {
     "should_trigger": [
       "For this new version of Next.js API, please check the official documentation before making a decision.",
@@ -113,6 +401,30 @@
       "Review token storage security"
     ]
   },
+  "cc-tauri-project-standard": {
+    "should_trigger": [
+      "Review Tauri command input validation",
+      "Restrict a Tauri 2 capability to one window",
+      "Review Tauri app command permission generation",
+      "Define a Tauri invoke error contract",
+      "Own Tauri managed-state shutdown",
+      "Bound blocking work in a Tauri core",
+      "Verify Tauri target bundle resources",
+      "Review Tauri plugin and sidecar authority",
+      "Review actual Tauri2 selected capability and app-command permission boundaries"
+    ],
+    "should_not_trigger": [
+      "Organize an ordinary Rust library with no Tauri",
+      "Tune a Node HTTP server without a WebView",
+      "Only adjust a React CSS margin",
+      "Design a Go CLI flag parser",
+      "Edit an Electron preload script",
+      "Translate a poster caption",
+      "Review a SQL execution plan",
+      "Format unrelated Python files",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
+  },
   "cc-tdd-methodology": {
     "should_trigger": [
       "Implement this hook using TDD",
@@ -156,5 +468,29 @@
       "Write a CLI unit test",
       "Polish marketing copy"
     ]
+  },
+  "cc-typescript-project-standard": {
+    "should_trigger": [
+      "Review or fix TypeScript SDK declaration exports",
+      "Review or fix TypeScript CLI NodeNext resolution",
+      "Review or fix TypeScript desktop preload contract",
+      "Review or fix TypeScript unknown input narrowing",
+      "Review or fix TypeScript discriminated union API",
+      "Review or fix TypeScript monorepo project references",
+      "Review or fix TypeScript generic library constraints",
+      "Review or fix TypeScript consumer type tests",
+      "Review a TypeScript library unknown-input boundary before effects without changing its module mode"
+    ],
+    "should_not_trigger": [
+      "Only adjust CSS spacing without code contracts",
+      "Translate product copy without programming",
+      "Generate a poster illustration",
+      "Choose a restaurant for dinner",
+      "Change a database index without language code",
+      "Design framework component routing without language configuration",
+      "Rewrite a marketing headline",
+      "Produce an audio soundtrack",
+      "Only translate prose mentioning the technology without modifying or reviewing a program"
+    ]
   }
 }