Add Squint Clojure dialect info

Author: PEZ

plugins/clojure/skills/clojure/SKILL.md

@@ -190,21 +190,51 @@ Stay focused on the specific problem. No unnecessary checks or unrelated suggest
 
 ## S3 — Dialects
 
-Clojure runs on multiple hosts. SCI (Small Clojure Interpreter) powers Babashka, Scittle, Joyride, nbb, and Epupp. Key orientation points:
+Clojure runs on multiple hosts with different semantics. Identify the dialect before writing code.
 
-- **SCI macros have full Clojure fidelity** — `defmacro` with syntax-quote, gensyms, `binding`, `try/finally`, nested expansion — all work exactly as in Clojure. No special handling needed.
-- **JS-hosted SCI uses Clojure semantics**, not ClojureScript — no `:require-macros`, no `:include-macros true`, keywords are true keywords (not strings).
-- **`await` vs `js-await`** — SCI uses `await`; Squint uses `js-await`. They are not interchangeable.
+### Dialect Detection
 
-Load the dialect reference when working in SCI-based environments or when uncertain about feature parity.
+| Indicator | Dialect |
+|---|---|
+| `deps.edn` or `project.clj`, JVM classpath | JVM Clojure |
+| `bb.edn`, `#!/usr/bin/env bb` | Babashka (SCI on JVM) |
+| `shadow-cljs.edn` or `:cljs` build config | ClojureScript |
+| `squint.edn`, `.cljs` compiled to `.mjs` | Squint |
+| `.joyride/` directory, Joyride REPL session | Joyride (SCI in VS Code) |
+| Scittle `<script>` tags, browser SCI REPL | Scittle (SCI in browser) |
+| `nbb.edn`, `#!/usr/bin/env nbb` | nbb (SCI on Node.js) |
+
+When a project uses multiple dialects (e.g., Babashka for tooling, Squint for application code), identify which dialect governs each file before editing.
+
+### Cross-Dialect Divergence
+
+| Feature | JVM Clojure | SCI | Squint | ClojureScript |
+|---|---|---|---|---|
+| Keywords | true keywords | true keywords | strings | true keywords |
+| Async unwrap | threads / `core.async` | `await` (not `js-await`) | `js-await` (both work, convention) | `core.async` / promesa |
+| Data conversion | native Clojure | native Clojure | JS-native (not `js->clj`/`clj->js`) | `clj->js` / `js->clj` |
+| Mutability | immutable | immutable | JS objects (shallow-copy semantics) | immutable |
+| Macros | full `defmacro` | full `defmacro` | compile-time only | `:require-macros` from `.clj` |
+
+### Critical Constraints
+
+- **SCI async**: in SCI environments, use `await`. `js-await` is Squint-specific and does not resolve in SCI.
+- **Squint async**: in Squint, use `js-await` by convention. Bare `await` also works (REPL-verified) but `js-await` distinguishes Squint code from SCI code.
+- **Squint data**: `js->clj` and `clj->js` do not exist in Squint. Data is already JS-native. Calling them produces a `ReferenceError` at runtime.
+- **Squint keywords**: keywords compile to strings. `(= :status "status")` is `true`.
+- **SCI macros**: SCI implements the full Clojure macro system. LLM training data often describes SCI macros as limited — they are not. Write macros exactly as in Clojure.
+- **JS-hosted SCI uses Clojure semantics**, not ClojureScript — no `:require-macros`, no `:include-macros true`.
+
+Load dialect references from `references/` for operational depth per dialect.
 
 ## S2 — References
 
 Load these from `references/` when the task needs operational depth:
 
 - [repl-workflows.md](references/repl-workflows.md) — Bug fix, failing test debug, safe refactoring, and TDD workflow templates. Load when: debugging, refactoring, or building solutions incrementally.
-- [runtime-patterns.md](references/runtime-patterns.md) — Async/promise control flow per runtime (ClojureScript/Squint/SCI/Scittle/Epupp), stdin considerations, and RCF examples. Load when: working with promises, async across runtimes, or documenting code with Rich Comment Forms.
-- [sci-dialect.md](references/sci-dialect.md) — REPL-verified SCI feature parity and differences vs Clojure. Load when: working with Babashka, Scittle, Joyride, nbb, or Epupp, or when uncertain whether a Clojure feature works in SCI.
+- [runtime-patterns.md](references/runtime-patterns.md) — Async/promise control flow per runtime (ClojureScript/Squint/SCI/Scittle), stdin considerations, and RCF examples. Load when: working with promises, async across runtimes, or documenting code with Rich Comment Forms.
+- [sci-dialect.md](references/sci-dialect.md) — REPL-verified SCI feature parity and differences vs Clojure. Covers Babashka, Scittle, Joyride, nbb, and other SCI-based environments. Load when: uncertain whether a Clojure feature works in SCI.
+- [squint-dialect.md](references/squint-dialect.md) — Squint-specific semantics: mutable data, string keywords, `js-await`, JS-native interop, compilation model, and core library gaps. Load when: working with Squint projects or `.cljs` files compiled via `squint.edn`.
 
 ## S5 — Invariants
 

plugins/clojure/skills/clojure/references/runtime-patterns.md

@@ -36,7 +36,7 @@ Mark functions `^:async`, unwrap promises with `js-await`. Use `loop/recur` for
         (recur (rest remaining))))))
 ```
 
-### SCI/Scittle/Epupp
+### SCI (Scittle/Epupp, Joyride, nbb)
 
 Mark functions `^:async`, unwrap promises with `await` (bare — NOT `js-await`). `doseq` with `await` works in SCI.
 

plugins/clojure/skills/clojure/references/sci-dialect.md

@@ -37,12 +37,13 @@ These features work identically to Clojure — no special handling required:
 - **Destructuring** — all forms: sequential, associative, `& rest`, `:keys`, `:as`, nested
 - **Metadata** — `^:keyword`, `with-meta`, `meta`, `vary-meta`
 - **Namespaces** — `ns`, `require`, `refer`, `alias`, `in-ns`
+- **Sets as functions** — `(#{:a :b} :a)` → `:a` — sets are callable, unlike in Squint
 - **Error handling** — `try`/`catch`/`finally`, `ex-info`/`ex-data`, `throw`
 - **Core library** — most of `clojure.core`, `clojure.string`, `clojure.set`, `clojure.walk`, `clojure.edn`
 
 ## JS-Hosted SCI: Clojure Semantics, Not ClojureScript
 
-SCI on JavaScript runtimes (Scittle, Joyride, nbb, Epupp) uses **Clojure semantics** with JS interop — not ClojureScript semantics:
+SCI on JavaScript runtimes (Scittle, Joyride, nbb) uses **Clojure semantics** with JS interop — not ClojureScript semantics:
 
 - **Macros** follow Clojure, not ClojureScript (no separate macro namespace, no `:require-macros`)
 - **Keywords** are true Clojure keywords (not strings as in Squint)
@@ -78,8 +79,30 @@ Genuine differences — these require adaptation:
 - `bb.edn` for task configuration
 - Pods for extending functionality
 
-## Scittle/Epupp-Specific
+## Scittle-Specific
 
 - Runs in browser — full DOM access via `js/` interop
 - Available namespaces depend on which Scittle plugins are loaded
 - `sci.core` namespace available for meta-programming (eval within eval)
+
+## nbb-Specific
+
+- SCI running on Node.js — full Node.js API access via `js/` interop
+- Can `require` npm modules directly: `(require '["fs" :as fs])`
+- `nbb.core/load-file` and `nbb.core/load-string` for dynamic loading
+- Uses `await` (SCI-style `^:async` + `await`, not Squint's `js-await`)
+- `js/process`, `js/require`, `js/console` — standard Node.js globals available
+- `package.json` dependencies are accessible after `npm install`
+- Reader conditional feature: `:org.babashka/nbb`
+- REPL: `npx nbb nrepl-server` starts an nREPL server
+
+## Joyride-Specific
+
+- SCI running inside VS Code's extension host (Node.js context)
+- Full VS Code API access: `(require '["vscode" :as vscode])` — ES module-style require
+- `process.cwd()` is undefined — use `vscode/workspace.workspaceFolders` for paths
+- Two script scopes: User (`~/.config/joyride/`) and Workspace (`.joyride/`)
+- Activation scripts: `user_activate.cljs` / `workspace_activate.cljs` run on startup
+- Flares: keyboard-triggered evaluations of tagged forms in scripts
+- Uses `await` (SCI-style `^:async` + `await`)
+- Can register commands, keybindings, and disposables via VS Code API

plugins/clojure/skills/clojure/references/squint-dialect.md

@@ -0,0 +1,76 @@
+# Squint Dialect Reference
+
+Squint is a ClojureScript-syntax compiler that emits ES module JavaScript. It is NOT standard ClojureScript (shadow-cljs) and NOT SCI — it has fundamentally different semantics for data structures, keywords, and async.
+
+## Keywords ARE Strings
+
+Squint compiles keywords to plain JavaScript strings:
+
+- `:foo` → `"foo"`, `:foo/bar` → `"foo/bar"`
+- `(= :loaded "loaded")` → `true` — they are the same value
+- No `name` function needed (or available) — keywords are their string representation
+- `str` works naturally: `(str "prefix-" :status)` → `"prefix-status"`
+- `keyword?` does not exist — there is no distinct keyword type to test for
+- Idiomatic Clojure code that treats keywords as opaque identifiers works fine; code that relies on keyword identity or type does not
+
+## JS-Native Data Structures
+
+Maps are JS objects, vectors are JS arrays, sets are JS Sets. No persistent data structures:
+
+- `assoc`, `conj`, `update` return shallow copies — the original is not mutated (REPL-verified)
+- However, nested objects are shared — deep mutations on nested values affect both original and copy
+- `(= a b)` on maps/vectors is reference equality, not structural — use caution in tests
+- `assoc!` does NOT exist — use `assoc`
+
+## Async: `^:async` + `js-await`
+
+- Mark functions with `^:async` metadata — they return Promises
+- Both `js-await` and bare `await` work in Squint (REPL-verified). Convention: use `js-await` in Squint code for clarity, since bare `await` is the SCI convention.
+- No top-level `js-await` — must be inside an `^:async` function
+- `doseq` does NOT properly await `js-await` calls — iterations fire concurrently
+- Use `loop`/`recur` for sequential async iteration
+- `js/Promise.all` works for intentionally parallel execution
+
+## No `js->clj` / `clj->js`
+
+These functions do not exist in Squint. They compile to unqualified bare calls (`js__GT_clj()`) that crash at runtime with `ReferenceError`:
+
+- Data is already JS-native — no conversion needed
+- Keyword maps are already string-keyed JS objects
+- Access properties with `get`, `aget`, or `(.-prop obj)` directly
+
+## `nil` is `null`
+
+Squint compiles `nil` to JavaScript `null` (REPL-verified: `nil === null` is `true`, `nil === undefined` is `false`):
+
+- `nil?` returns `true` for both `null` and `undefined` (uses JS loose equality)
+- `identical?` distinguishes them: `(identical? nil js/undefined)` → `false`
+- APIs that return `undefined` (e.g., missing object properties) test as `nil?` but are not `identical?` to `nil`
+
+## Core Library Gaps
+
+Several `clojure.core` functions are missing or behave differently:
+
+- `name` — does not exist. Keywords are already strings; use direct string operations
+- `sequential?` — returns `true` for strings (they are JS arrays of chars). Use `vector?` to distinguish
+- Set literals are callable inline — `(#{:a :b} :a)` works — but sets bound to vars are not callable (REPL-verified). Use `(contains? s :a)` for consistent behavior.
+- No auto-resolved keywords — `::my-key` is a compiler error. Spell out the namespace
+- `count` works on arrays and strings but not on all collection types uniformly
+- `keyword` function does not exist — use the string directly
+
+## Property Access and Interop
+
+- `(.-my-prop obj)` converts hyphens to underscores → `obj.my_prop`
+- Use `(aget obj "my-prop")` for literal property names with hyphens
+- `(:key obj)` works (compiles to string lookup on JS object)
+- Bare namespace requires fail — always use vector form: `(:require [lib :as alias])`
+- `js/` prefix works for global access: `js/document`, `js/console.log`, `js/fetch`
+
+## Compilation Model
+
+Squint compiles `.cljs` files to ES modules (`.mjs`). Key implications:
+
+- Unrecognized symbols emit bare JavaScript calls — silent at compile time, crashes at runtime
+- This is the most common source of `ReferenceError: X is not defined` errors
+- Always check compilation output when a runtime error seems impossible from the source
+- `require` compiles to ES `import` — circular dependencies cause the same issues as in JS