diff --git a/spacecraft-typescript-guidelines.skill b/spacecraft-typescript-guidelines.skill index 4c79643..a9224f1 100644 Binary files a/spacecraft-typescript-guidelines.skill and b/spacecraft-typescript-guidelines.skill differ diff --git a/spacecraft-typescript-guidelines.zip b/spacecraft-typescript-guidelines.zip index 70be324..5bf07b8 100644 Binary files a/spacecraft-typescript-guidelines.zip and b/spacecraft-typescript-guidelines.zip differ diff --git a/spacecraft-typescript-guidelines/SKILL.md b/spacecraft-typescript-guidelines/SKILL.md index b6f4dfc..c591446 100644 --- a/spacecraft-typescript-guidelines/SKILL.md +++ b/spacecraft-typescript-guidelines/SKILL.md @@ -1,6 +1,6 @@ --- name: spacecraft-typescript-guidelines -description: Use for writing type-safe highly-concurrent optimized TypeScript code targeting TypeScript 7.0+ (Go-based native compiler). Triggers on any request involving TypeScript, tsc, tsconfig.json, project references (composite, incremental), type-safety (strict, unknown vs. any), discriminated unions, exhaustive never checks, async concurrency (Promises, worker_threads), V8 runtime optimizations (hidden classes, Map/Set, flat arrays), runtime schema validation (Zod, ArkType), or ts6-shims. Trigger even when implicit, e.g. "typecheck this TS project", "create a worker pool in TS", "configure tsconfig for monorepo", or "make this TS compiler run faster". Do NOT trigger for standard JavaScript (unless type-safety is requested) or other languages. By Mohamed Hammad and Spacecraft Software. +description: Use for writing type-safe highly-concurrent optimized TypeScript code targeting TypeScript 7.0+ (Go-based native compiler). Triggers on any request involving TypeScript, tsc, tsconfig.json, project references, type-safety (strict, unknown vs. any), discriminated unions, exhaustive never checks, async concurrency (Promises, worker_threads), V8 optimizations (hidden classes, Map/Set), runtime schema validation (Zod, ArkType), or ts6-shims. ALSO triggers on any request to author or review JavaScript — .js/.mjs/.cjs, package.json, Node/Deno/Bun, Electron, an npm package, a VS Code extension, a browser script — because Standard §3.1.1 requires TypeScript source wherever the JavaScript runtime is needed; load this skill to convert it or to file the exemption. Trigger even when implicit, e.g. "typecheck this TS project", "write a quick Node script", or "create a worker pool in TS". Do NOT trigger for other languages. By Mohamed Hammad and Spacecraft Software. license: GPL-3.0-or-later maintainer: Mohamed Hammad website: https://Construct.SpacecraftSoftware.org/ @@ -14,6 +14,21 @@ website: https://Construct.SpacecraftSoftware.org/ **You are an expert TypeScript systems engineer at Spacecraft Software specializing in type-safe, high-performance, and concurrent systems targeting TypeScript 7.0+ (the native Go-based compiler).** Always follow these rules when writing or reviewing TypeScript code. Never deviate. This skill is fully compatible with Claude 3.5 Sonnet, Claude 4, and other advanced models — instructions are explicit, checklist-driven, and self-contained. +## §3.1.1 — TypeScript over JavaScript (read this first) + +**The Steelbore Standard §3.1.1 makes TypeScript mandatory wherever the JavaScript runtime is required.** JavaScript is dynamically typed, so whole classes of defect that a compiler would reject survive into production as run-time failures. The memory-safety lever of §3.1 does not apply here — the runtime is memory-safe either way — so **type safety is the Priority 1 lever on this runtime**, and it is required, not encouraged. + +**If you were asked to write or review plain JavaScript, you are in the right place.** Work the gate in order: + +1. **Is a memory-safe alternative available?** Rust compiled to WebAssembly, Rust or Go for a server, Flutter/Dart for an application UI. If so, §3.1 chooses it over the JavaScript runtime entirely — raise that before writing either language. +2. **Is the JavaScript runtime genuinely required?** A browser page, a Node/Deno/Bun program, an Electron application, an npm-distributed tool, a VS Code extension. If so, **author it in TypeScript** and apply the rest of this skill. Do not write the `.js` and offer to convert it later. +3. **Does a §3.1.1 exemption cover it?** Three cases need no filing: a tool's own configuration file that must be `.js` (e.g. `eslint.config.js` where no TypeScript loader is available), a vendored or upstream-derived file carried under §4.2, and generated output. Emitted `.js` and source maps in a build directory are derived artifacts and out of scope — the rule governs what is *authored and committed*. +4. **Anything else** — including "it is only a small script" — requires a **documented technical exemption** in the project's README or architecture notes, on the same footing as the §3.1 memory-safe-language exemption. Say so plainly rather than writing the JavaScript silently. + +When converting an existing `.js` file, the destination is strict-mode TypeScript per the sections below; a rename that leaves `any` everywhere satisfies neither §3.1.1 nor this skill. + +> **Transpiling is not typechecking.** esbuild, SWC, and Bun strip types without checking them. §3.1.1 requires `tsc --noEmit` (or the equivalent project-wide check) to gate CI — a project that only transpiles has not satisfied the section. + ## Core Philosophy - **Stability first (Standard §3 Priority 1).** TypeScript compile-time checks are your primary guarantee. Enable the strictest compiler configurations (`strict: true`); never compromise type safety by using escape hatches (`any` or `as any`) unless documenting a verified FFI/dynamic boundary. - **Then Performance (Priority 2).** TypeScript compiles to JavaScript executed on the V8 engine (Node.js/Bun/Deno/Browser). Write V8-friendly code by keeping object shapes stable (hidden classes), avoiding GC churn on hot loops, and choosing optimized collections (`Map`/`Set`) over raw objects. @@ -60,6 +75,9 @@ Always choose the concurrency model corresponding to the workload: - **Testing:** Vitest or Jest for unit testing; property testing via `fast-check` to assert type invariants. ## Anti-Patterns (Never Do These) +- Authoring a new `.js`/`.mjs`/`.cjs` source file outside the §3.1.1 exemptions — write TypeScript, or file the exemption. +- Using `@ts-ignore` to silence a diagnostic. §3.1.1 prohibits it outright; use `@ts-expect-error` with a comment naming the reason, so the suppression fails the build once it becomes unnecessary. +- Shipping a build that only transpiles (esbuild/SWC/Bun) with no `tsc --noEmit` gate in CI. - Using `any` or `as any` to mute compiler warnings. - Invoking synchronous file or process commands (`readFileSync`, `execSync`) in production web servers. - Spawning worker threads on-demand for short-lived task requests. @@ -68,6 +86,8 @@ Always choose the concurrency model corresponding to the workload: - Programmatic Webpack/ESLint builds pointing to TS 7.0 programmatic compiler API (use TS 6 compatibility package). ## Pre-Commit Checklist (Verify Every Time) +- [ ] **§3.1.1:** every authored source file is TypeScript, or is covered by a listed exemption / a documented one in the README +- [ ] **§3.1.1:** `tsc --noEmit` (not just the bundler) gates CI; no `@ts-ignore` anywhere - [ ] `strict: true` and all strict compiler flags are configured in `tsconfig.json` - [ ] No `any` type annotations or non-null assertions (`!`) left in source code - [ ] Union checks are exhaustive and validated with the `never` type assert