Skip to content

policy: Deno is to go, Bun goes first — correct the governing document #655

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hyperpolymath wants to merge 2 commits into
base: main
Choose a base branch
from
+33 −9
Open

policy: Deno is to go, Bun goes first — correct the governing document #655

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f6accdf
policy: Deno is to go, Bun goes first — correct the governing document
hyperpolymath Aug 26, 2026
c5912a1
policy: no TypeScript at all; Deno moves to BANNED; pin bunx
hyperpolymath Aug 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 33 additions & 9 deletions .claude/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,7 @@ for the canonical statement.
| Language/Tool | Use Case | Notes |
|---------------|----------|-------|
| **AffineScript** | Primary application code | Compiles to typed-wasm; affine/linear types. Replaces ReScript across the estate (RS/TS/JS → AffineScript → typed-wasm). |
| **Bun** | JS/TS runtime & package management (tier 1) | Default for all new work. Executes `.ts` directly, no build step. Uses an npm-compatible `package.json` plus `bun.lock` — both are expected, not anti-patterns. |
| **Deno** | JS/TS runtime (tier 2) | Grandfathered. Existing Deno projects need not migrate; prefer over pnpm/npm where Bun cannot be used. |
| **Bun** | JS runtime & package management (tier 1) | Default for all new work. Runs compiled ESM/JS directly — no bundler step. Uses an npm-compatible `package.json` plus `bun.lock` — both are expected, not anti-patterns. |
| **Rust/SPARK** | Performance-critical, systems, WASM, CLI tools, safety-critical | "Rust" always means "Rust/SPARK" per terminology note above. Preferred over Ada where reachable. |
| **Zig** | **APIs, FFIs, gateways, client SDKs (estate default 2026-05-28)**, memory-safe systems where Rust/SPARK is overkill | Zig is the estate-wide default for all API/FFI/gateway/client-SDK work unless explicitly special-cased; Idris2 owns ABIs. Completed V-lang→Zig migration 2026-05-28. |
| **Idris2** | Formal verification (primary, ABI-style proofs) | ATS2 rejected. Proven-library status in `proven` repo. |
Expand Down Expand Up @@ -120,18 +119,43 @@ for the canonical statement.
>
> The distinction that keeps both documents coherent: **Bun is the runtime, tier 1
> and unchanged; AffineScript is the language for new application code.** Those
> were run together in the withdrawn text. TypeScript is permitted only where
> AffineScript cannot reach — the same narrow, transitional carve-out JavaScript
> holds below.
> were run together in the withdrawn text.
>
> ⚠ **TIGHTENED 2026-08-27 — owner ruling.** Asked about the Bun row advertising direct
> `.ts` execution, the owner ruled: *"no typescript … that should not exist at all."*
> The previous sentence here read "TypeScript is permitted only where AffineScript cannot
> reach". That is now **too permissive**: TypeScript is not a fallback tier, and no tool
> description in this file may advertise TypeScript support. Every `.ts` reference has been
> removed from the Bun row, including "JS/TS" in its label.
>
> ⚠ **This collides with the "TypeScript Exemptions (Approved)" table below**, which
> documents real technical carve-outs — `.d.ts` declaration files, the VS Code extension
> host (npm/Node-native, `@vscode/test-electron` has no alternative), and MCP/LSP protocol
> glue. Those are **not** stylistic preferences and cannot simply be deleted. They are left
> standing and flagged for an explicit owner decision: either retire each carve-out with a
> migration path, or restate the rule as "no new TypeScript, these listed exemptions
> excepted". **Not resolved unilaterally.**
>
> ReScript's ban is uncontested, and its migration destination is **AffineScript**.

> **SUPERSEDED 2026-08-26 — Deno is no longer tier 2.** The owner ruled:
> *"deno is to go and bun is the way we are going, put it first everywhere unless not
> possible and explain why if not."* The "Bun > Deno > pnpm > npm" ordering above described
> a **preference**; it is now a **removal**. Deno has been **moved out of ALLOWED into BANNED** accordingly - a struck-through row in an ALLOWED table is ambiguous to the agents that read this file (codacy raised exactly that on #655).
>
> This matters because this file is what agents read first. While it said Deno was
> "grandfathered … need not migrate", agents correctly declined to migrate — and the
> dependency rules below compounded it: *"No package.json for runtime deps — use deno.json
> imports"* left repos with **no manifest at all**. `hyperpolymath/ubicity` could not build
> under any toolchain for exactly this reason (see ubicity#107). Both rules are corrected.

### BANNED - Do Not Use

| Banned | Replacement | Notes |
|--------|-------------|-------|
| TypeScript | AffineScript | RS/TS/JS → AffineScript → typed-wasm. |
| **ReScript** | AffineScript | Banned in new code as of 2026-04-30. Existing `.res` files migrate to `.affine` directly (do not pass through ReScript). |
| **Deno** | Bun | **Being removed.** Owner ruling 2026-08-26: *"deno is to go and bun is the way we are going, put it first everywhere unless not possible and explain why if not."* Existing Deno projects must migrate to Bun; where Bun genuinely cannot be used, the reason must be documented in the repo. Assessment of all 30 remaining `deno.json` locations: #658. |
| Node.js | Bun | Bun is Node-compatible; run the code, drop the runtime. |
| npm | Bun | npm is tier 4 — *permitted, never preferred*, not banned. `package-lock.json` must still not be tracked (standards#67). |
| yarn | Bun | yarn is not in the tier list at all. |
Expand Down Expand Up @@ -179,13 +203,13 @@ Both are FOSS with independent governance (no Big Tech).
(`docs/migrations/js-to-affinescript`) carves out MCP/LSP protocol glue and
VSCode-host code (*"MCP glue … Should NOT appear in `portable now`"*). Those
stay until the AffineScript MCP/LSP/VSCode bindings ship (affinescript#446).
Genuinely-portable Deno CLI scripts are the convert-now bucket.
Genuinely-portable Deno CLI scripts are the convert-now bucket; anything not yet portable to AffineScript moves to **Bun**, not left on Deno.
- **Compile-verify, wire-first.** A port is not done until the `.affine` builds
green (`just check`) and the compiled output is wired as the live entry with
the original removed *in the same PR*. Never ship an unbuilt `.affine` or
delete a working `.ts`/`.res` for one that has not compiled.
2. **No package.json for runtime deps** - Use deno.json imports
3. **No node_modules in production** - Deno caches deps automatically
2. **Use `package.json` + `bun.lock` for JS runtime deps** - Bun is npm-compatible; a manifest is REQUIRED. (This line previously said "No package.json - use deno.json imports", which left repos with undeclared dependencies that could not build under any toolchain.)

@codacy-production codacy-production Bot Aug 26, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ LOW RISK

Nitpick: Remove historical commentary (e.g., 'This line previously said...') from the enforcement rule. This context is already appropriately captured in the superseding note at line 129; keeping the rule concise improves clarity for agent consumption.

3. **`bun install --production` for production deps** - Bun resolves from `package.json` and pins via `bun.lock`
4. **No Go code** - Use Rust instead
5. **No Python** - All Python must be rewritten
6. **No Kotlin/Swift for mobile** - Use Tauri 2.0+ or Dioxus
Expand All @@ -195,7 +219,7 @@ Both are FOSS with independent governance (no Big Tech).

- **Primary**: Guix (guix.scm)
- **Fallback**: Nix (flake.nix)
- **JS deps**: Deno (deno.json imports)
- **JS deps**: **Bun** (`package.json` + `bun.lock`); `bunx <tool>` to run one-off tooling

### Documentation Format

Expand Down
Loading