policy: Deno is to go, Bun goes first — correct the governing document - #655
policy: Deno is to go, Bun goes first — correct the governing document#655hyperpolymath wants to merge 2 commits into
Conversation
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".
This file is what agents read first and it currently says the opposite, so it
is corrected before any repo is touched - otherwise every future agent
re-derives the wrong conclusion from the governing document.
:89 Deno "tier 2, grandfathered, need not migrate"
-> BEING REMOVED; existing projects must migrate to Bun, and where Bun
genuinely cannot be used the reason must be DOCUMENTED, not left
silently on Deno
:187 "No package.json for runtime deps - use deno.json imports"
-> Use package.json + bun.lock; Bun is npm-compatible and a manifest is
REQUIRED
:188 "No node_modules in production - Deno caches automatically"
-> bun install --production, pinned via bun.lock
:198 "JS deps: Deno (deno.json imports)"
-> JS deps: Bun (package.json + bun.lock), bunx for one-off tooling
:182 portable Deno CLI scripts are the convert-now bucket
-> ...and anything not yet portable to AffineScript moves to Bun
WHY :187 MATTERS MOST. "No package.json for runtime deps" did not express a
preference - it told repos not to declare their dependencies at all.
hyperpolymath/ubicity is the worked example: its sources import zod and glob,
it had NO manifest of any kind, and it could not build under ANY toolchain.
Fixed in ubicity#107 by deriving a manifest from the imports; the rule that
caused it is fixed here.
Policy text only - no code, no workflows. The policy table (30 rows) and
blockquote structure are intact.
NOTED, NOT CHANGED: :197 still reads "Fallback: Nix (flake.nix)". Nix was
deprecated for Guix by ADR-2026-STACK-MIGRATION, so that looks stale too, but
it is a separate ruling and is not folded into a Deno/Bun correction.
Follow-on: 30 repos carry a live deno.json - working task runners, not orphaned
config - tracked separately for migration with documented exceptions.
|
Warning Review limit reachedNext included review available in 53 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
|
Up to standards ✅🟢 Issues
|
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull Request Overview
This PR successfully codifies the 2026-08-26 owner ruling to transition from Deno to Bun as the Tier 1 JS/TS runtime. The updates to the enforcement rules—specifically mandating 'package.json' and 'bun.lock'—resolve critical buildability issues in downstream consumers.
While the core requirements are addressed, two primary areas for improvement were identified to ensure policy effectiveness:
- AI Agent Compatibility: The use of strikethroughs in the Language Policy table may be ignored by LLM-based parsers. Relocating Deno to a 'BANNED' section ensures unambiguous enforcement by agents.
- Systemic Inconsistency: The document retains Nix as a fallback on line 208, which contradicts the broader move toward Guix as specified in ADR-2026-STACK-MIGRATION.
Codacy quality standards are met, and the implementation aligns with the mandated dependency management rules.
About this PR
- There is a systemic inconsistency on line 208, which still lists Nix as a fallback. This contradicts ADR-2026-STACK-MIGRATION, which favors Guix for the infrastructure stack. It is recommended to align this line with the current migration strategy.
Test suggestions
- Verify the Language Policy table reflects Deno's removal and the migration mandate.
- Verify the Enforcement Rules section (Rule 2 and 3) requires manifests and production locks.
- Verify the Package Management section lists Bun as the source for JS deps.
- Verify the presence of the explanatory blockquote regarding the 2026-08-26 ruling.
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
| | **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. | | ||
| | **Deno** | ~~JS/TS runtime~~ **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 — not left silently on Deno. | |
There was a problem hiding this comment.
🟡 MEDIUM RISK
Suggestion: The inclusion of Deno in the 'ALLOWED' table (even with strikethrough) poses a risk for AI agents that may fail to parse markdown formatting like ~~. Additionally, the policy requires documenting Bun exceptions; to ensure consistency with the estate's machine-readable standards, this should be explicitly pointed to .machine_readable/META.a2ml. It is recommended to move Deno to the 'BANNED' table and update the migration documentation accordingly.
| 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.) |
There was a problem hiding this comment.
⚪ 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.
Review feedback on #655 plus a tightened owner ruling. 1. NO TYPESCRIPT (owner, 2026-08-27). Asked about the Bun row advertising direct .ts execution, the owner ruled: "no typescript ... that should not exist at all." Every .ts reference is removed from the Bun row, including "JS/TS" in its label; it now reads "JS runtime". The blockquote sentence "TypeScript is permitted only where AffineScript cannot reach" is marked TOO PERMISSIVE. FLAGGED, NOT RESOLVED: this collides with the "TypeScript Exemptions (Approved)" table, which documents real technical carve-outs (.d.ts files, the npm/Node-native VS Code extension host, MCP/LSP glue). Those are not stylistic and cannot simply be deleted, so they are left standing and marked for an explicit owner decision rather than settled unilaterally. 2. DENO MOVED OUT OF ALLOWED INTO BANNED (codacy, #655). A struck-through row in an ALLOWED table is ambiguous to the agents that read this file - codacy raised exactly that. Deno now appears once, in BANNED, carrying the ruling and pointing at the #658 assessment. 3. UNPINNED bunx (coderabbitai, Security & Privacy). A bare `bunx <tool>` can fetch a package outside package.json/bun.lock and can start Node via a shebang. Guidance now requires a declared devDependency plus `bunx --no-install --bun <tool>`. NOT TAKEN: "a npm-compatible" (LanguageTool is wrong; "an" is correct before a vowel sound). "Remove the historical commentary" - the history is why the file was wrong before, and deleting it invites the same drift back. STILL FLAGGED, unchanged: "Fallback: Nix (flake.nix)" is stale under ADR-2026-STACK-MIGRATION, but that is a separate ruling and is deliberately not folded into a Deno/Bun change.
|
1 participant
Owner ruling, 2026-08-26:
This file is what agents read first, and it currently says the opposite. Correcting it before touching any repo, because otherwise every future agent re-derives the wrong conclusion from the governing document.
What was wrong
package.jsonfor runtime deps" — usedeno.jsonimportspackage.json+bun.lock; Bun is npm-compatible and a manifest is requirednode_modulesin production" — Deno caches automaticallybun install --production, pinned viabun.lockdeno.jsonimports)package.json+bun.lock),bunxfor one-off toolingWhy line 187 matters most
"No
package.jsonfor runtime deps" did not merely express a preference — it told repos not to declare their dependencies at all.hyperpolymath/ubicityis the worked example: its sources importzodandglob, it had no manifest of any kind, and it therefore could not build under any toolchain — not Bun, not Node, not Deno. That was fixed in ubicity#107 by deriving a manifest from the imports. The rule that caused it is fixed here.Scope
Policy text only. No code, no workflows. 16 insertions, 5 deletions; the policy table (30 rows) and blockquote structure are intact.
Noted, not changed
Line 197 still reads "Fallback: Nix (
flake.nix)". Nix was deprecated in favour of Guix byADR-2026-STACK-MIGRATION, so that line looks stale too — but that is a separate ruling and I have not folded it into a Deno/Bun correction. Flagging for a decision.Follow-on
30 repos carry a live
deno.json— these are not orphaned config but working task runners (deno run -A npm:affinescript,deno test --allow-read). Migrating them to Bun is tracked separately, with a documented justification for any that genuinely cannot move.