From 99fa9323bb7b59a211d60651a718fb475923eaa7 Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Tue, 4 Aug 2026 23:54:32 +0000 Subject: [PATCH] =?UTF-8?q?feat(typescript-guidelines):=20fire=20on=20Java?= =?UTF-8?q?Script,=20gate=20on=20Standard=20=C2=A73.1.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The description's negative trigger — "Do NOT trigger for standard JavaScript (unless type-safety is requested)" — became wrong the moment §3.1.1 landed. The one point at which this skill most needs to load is when someone reaches for plain JavaScript, because that is exactly when the Standard says to stop and write TypeScript instead. As written, the skill reached only those who had already chosen TypeScript: the audience that needs the rule least. Description: the negative JS trigger is replaced by a positive one — .js/.mjs/.cjs, package.json, Node/Deno/Bun, Electron, npm packages, VS Code extensions, browser scripts — with the reason stated inline so the loading agent knows what to do on arrival (convert, or file the exemption). Trimmed the V8 and project-reference clauses to pay for it: 966 rendered characters against the §5.6 cap of 1000. Body: new "§3.1.1 — TypeScript over JavaScript (read this first)" section ahead of Core Philosophy, giving the four-step gate — prefer a memory-safe alternative, else author TypeScript, else check the three no-filing exemptions, else document one — plus the transpiling-is-not- typechecking note. Anti-Patterns gains authoring stray .js, @ts-ignore, and bundler-only CI; the pre-commit checklist gains two §3.1.1 lines. Both bundles rebuilt and byte-verified against the working tree. Co-Authored-By: Claude Opus 5 (1M context) --- spacecraft-typescript-guidelines.skill | Bin 7712 -> 8983 bytes spacecraft-typescript-guidelines.zip | Bin 7928 -> 9199 bytes spacecraft-typescript-guidelines/SKILL.md | 22 +++++++++++++++++++++- 3 files changed, 21 insertions(+), 1 deletion(-) diff --git a/spacecraft-typescript-guidelines.skill b/spacecraft-typescript-guidelines.skill index 4c7964309e8910307d86a98ce3a16929debd67ca..a9224f14fe804b6232e99acf7191b07cbe6b1ec4 100644 GIT binary patch delta 5462 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 M9eD=*ApigX0NxO?`2YX_ delta 4190 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 G0001!{{vtE 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