Port Sqids to pure CLJC and harden quality tooling

This replaces the prior sqids-java/sqids-javascript integration with a native
Clojure/ClojureScript implementation while keeping the public API stable.
The algorithm path is now shared in CLJC, supports large integer domains,
and improves readability with clearer naming, structure, and inline docs.

Internally, encode/decode now run through a total result-oriented core so
validation and error behavior are explicit and testable across platforms.
Throwing is constrained to the public edge functions

affected by API contracts. Platform-specific behavior was pushed into
platform namespaces to reduce reader-conditionals and duplicated logic.

Tooling was modernized for a model public Clojure library: local wrappers for
clj-kondo and cljstyle, stricter lint policy, markdownlint + prettier hooks,
Babashka-based blocklist generation, and a simplified test entrypoint via
Kaocha.

Testing and CI were expanded with always-on coverage enforcement,
machine-readable coverage outputs, JUnit XML reporting, and artifact uploads.
Specs and generators were strengthened to exercise canonical/erroneous decode
paths more directly and improve failure quality.

Documentation and contributor guidance were updated throughout, including
repository standards in AGENTS.md and clearer maintenance/release workflows.

Author: robhanlon22

.clj-kondo/config.edn

@@ -0,0 +1,109 @@
+{:linters
+ {:aliased-namespace-symbol {:level :error}
+  :aliased-namespace-var-usage {:level :error}
+  :aliased-referred-var {:level :error}
+  :case-quoted-test {:level :error}
+  :case-symbol-test {:level :error}
+  :clj-kondo-config {:level :error}
+  :cond-else {:level :error}
+  :condition-always-true {:level :error}
+  :consistent-alias {:level :error
+                     :aliases {clojure.edn edn
+                               clojure.set set
+                               clojure.spec.alpha s
+                               clojure.spec.gen.alpha gen
+                               clojure.string str
+                               clojure.test t}}
+  :def-fn {:level :error}
+  :deprecated-namespace {:level :error}
+  :deprecated-var {:level :error}
+  :destructured-or-always-evaluates {:level :error}
+  :destructured-or-binding-of-same-map {:level :error}
+  :discouraged-java-method {:level :error}
+  :discouraged-namespace {:level :error}
+  :discouraged-tag {:level :error}
+  :discouraged-var {:level :error}
+  :do-template {:level :error}
+  :docstring-leading-trailing-whitespace {:level :error}
+  :docstring-no-summary {:level :error}
+  :duplicate-key-args {:level :error}
+  :duplicate-refer {:level :error}
+  :earmuffed-var-not-dynamic {:level :error}
+  :equals-expected-position {:level :error
+                             :position :first}
+  :equals-false {:level :error}
+  :equals-float {:level :error}
+  :equals-nil {:level :error}
+  :equals-true {:level :error}
+  :if-nil-return {:level :error}
+  :inline-def {:level :error}
+  :is-message-not-string {:level :error}
+  :keyword-binding {:level :error}
+  :line-length {:level :error
+                :max-line-length 120}
+  :locking-suspicious-lock {:level :error}
+  :loop-without-recur {:level :error}
+  :main-without-gen-class {:level :error}
+  :min-clj-kondo-version {:level :error}
+  :minus-one {:level :error}
+  :missing-body-in-when {:level :error}
+  :missing-clause-in-try {:level :error}
+  :missing-docstring {:level :error}
+  :missing-else-branch {:level :error}
+  :missing-protocol-method {:level :error}
+  :missing-test-assertion {:level :error}
+  :multiple-async-in-deftest {:level :error}
+  :non-arg-vec-return-type-hint {:level :error}
+  :not-empty? {:level :error}
+  :plus-one {:level :error}
+  :reduce-without-init {:level :error}
+  :redundant-call {:level :error}
+  :redundant-do {:level :error}
+  :redundant-expression {:level :error}
+  :redundant-fn-wrapper {:level :error}
+  :redundant-format {:level :error}
+  :redundant-ignore {:level :error}
+  :redundant-let {:level :error}
+  :redundant-let-binding {:level :error}
+  :redundant-nested-call {:level :error}
+  :redundant-primitive-coercion {:level :error}
+  :redundant-str-call {:level :error}
+  :refer {:level :error}
+  :refer-all {:level :error}
+  :redefined-var {:level :error}
+  :schema-misplaced-return {:level :error}
+  :self-requiring-namespace {:level :error}
+  :shadowed-fn-param {:level :error}
+  :shadowed-var {:level :error}
+  :single-key-in {:level :error}
+  :single-logical-operand {:level :error}
+  :single-operand-comparison {:level :error}
+  :underscore-in-namespace {:level :error}
+  :unbound-destructuring-default {:level :error}
+  :uninitialized-var {:level :error}
+  :unreachable-code {:level :error}
+  :unresolved-excluded-var {:level :error}
+  :unresolved-namespace {:level :error}
+  :unresolved-protocol-method {:level :error}
+  :unresolved-var {:level :error}
+  :unquote-not-syntax-quoted {:level :error}
+  :unsorted-imports {:level :error}
+  :unsorted-required-namespaces {:level :error
+                                 :sort :case-insensitive}
+  :unused-alias {:level :error}
+  :unused-binding {:level :error
+                   :exclude-destructured-keys-in-fn-args false
+                   :exclude-destructured-as false
+                   :exclude-defmulti-args false}
+  :unused-excluded-var {:level :error}
+  :unused-import {:level :error}
+  :unused-namespace {:level :error
+                     :simple-libspec false}
+  :unused-private-var {:level :error}
+  :unused-referred-var {:level :error}
+  :unused-value {:level :error}
+  :use {:level :error}
+  :used-underscored-binding {:level :error}
+  :var-same-name-except-case {:level :error}
+  :warn-on-reflection {:level :error
+                       :warn-only-on-interop true}}}

.github/workflows/clojure.yml

@@ -23,7 +23,7 @@ jobs:
         name: Set up Java
         with:
           distribution: temurin
-          java-version: 11
+          java-version: 21
       - uses: actions/setup-python@v4
         name: Set up Python
         with:
@@ -34,10 +34,6 @@ jobs:
         with:
           path: ~/.cache/pre-commit
           key: ${{ runner.os }}-pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
-      - name: Docker cache
-        uses: ScribeMD/docker-cache@0.3.6
-        with:
-          key: ${{ runner.os }}-docker-${{ hashFiles('.pre-commit-config.yaml') }}
       - uses: actions/cache@v3
         name: Clojure cache
         with:
@@ -47,19 +43,32 @@ jobs:
             ~/.clojure
             ~/.cpcache
           key: ${{ runner.os }}-clojure-${{ hashFiles('deps.edn') }}
-      - name: Install Clojure
-        run: |
-          curl -L -O https://github.com/clojure/brew-install/releases/latest/download/posix-install.sh
-          chmod +x posix-install.sh
-          sudo ./posix-install.sh
-          rm posix-install.sh
+      - name: Install Clojure tools
+        uses: DeLaGuardo/setup-clojure@13
+        with:
+          cli: latest
+          bb: latest
+          clj-kondo: 2026.01.19
+          cljstyle: 0.15.0
       - name: Run pre-commit hooks
         run: |
           pip install -r requirements.txt
-          pre-commit run --all-files
-      - name: Run clj tests
-        run: bin/test clj
-      - name: Run cljs tests
+          SKIP=kaocha-test pre-commit run --all-files
+      - name: Run tests
         run: |
           npm install
-          bin/test cljs
+          bin/kaocha
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: target/coverage
+          if-no-files-found: warn
+      - name: Upload JUnit XML artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-xml
+          path: target/test-results/junit.xml
+          if-no-files-found: warn

.gitignore

@@ -1,4 +1,5 @@
-*.class *.iml
+*.class
+*.iml
 *.jar
 *.log
 *.swp
@@ -7,13 +8,19 @@
 .calva/output-window/
 .classpath
 .clj-kondo/.cache
+.cljs_node_repl/
 .cpcache
+.cpcache/
 .eastwood
 .factorypath
 .hg/
 .hgignore
 .idea
 .lein-*
+.lein-deps-sum
+.lein-failures
+.lein-plugins/
+.lein-repl-history
 .lsp/.cache
 .lsp/sqlite.db
 .nrepl-*
@@ -28,9 +35,14 @@
 .sw*
 .vscode
 /checkouts
+/checkouts/
 /classes
+/classes/
+/lib/
+/out
 /src/gen
 /target
+/target/
 Brewfile.lock.json
 cljs-test-runner-out/
 node_modules/

.markdownlint-cli2.yaml

@@ -0,0 +1,5 @@
+---
+config:
+  MD013: false
+ignores:
+  - node_modules/**

.pre-commit-config.yaml

@@ -1,38 +1,52 @@
 repos:
-  - repo: https://github.com/clj-kondo/clj-kondo
-    rev: v2023.10.20
-    hooks:
-      - id: clj-kondo-docker
-        pass_filenames: false
-        require_serial: true
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v6.0.0
     hooks:
       - id: check-shebang-scripts-are-executable
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-added-large-files
   - repo: https://github.com/scop/pre-commit-shfmt
-    rev: v3.7.0-4
+    rev: v3.12.0-2
     hooks:
-      - id: shfmt-docker
-        entry: mvdan/shfmt:v3.7.0
+      - id: shfmt
         args: [-w, -s, -i, "2"]
   - repo: https://github.com/koalaman/shellcheck-precommit
-    rev: v0.9.0
+    rev: v0.11.0
     hooks:
       - id: shellcheck
   - repo: local
     hooks:
+      - id: clj-kondo
+        name: clj-kondo
+        entry: bin/_clj-kondo --lint src test bin/update-blocklist build.clj deps.edn tests.edn shadow-cljs.edn
+        language: system
+        pass_filenames: false
+        require_serial: true
       - id: cljstyle
         name: cljstyle
         entry: bin/_cljstyle fix
         language: system
         types: [file]
+      - id: kaocha-test
+        name: kaocha-test
+        entry: bin/kaocha
+        language: system
+        pass_filenames: false
+        always_run: true
+        require_serial: true
+      - id: markdownlint-cli2
+        name: markdownlint-cli2
+        language: node
+        entry: markdownlint-cli2
+        additional_dependencies: ["markdownlint-cli2@0.21.0"]
+        types: [markdown]
+        args: ["--config", ".markdownlint-cli2.yaml", "--fix"]
       - id: prettier
         name: prettier
-        language: docker_image
-        entry: tmknom/prettier
+        language: node
+        entry: prettier
+        additional_dependencies: ["prettier@3.8.1"]
         types: [text]
         args: [--write, --list-different, --ignore-unknown]
       - id: git-diff

AGENTS.md

@@ -0,0 +1,65 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- Core library code lives in `src/org/sqids/`.
+- Cross-platform API is in `clojure.cljc`; specs are colocated in owning `.cljc` namespaces (`alphabet`, `block_list`, `encoding`, `decoding`, `init`, `results`).
+- Platform-specific helper functions are in `platform.clj` (JVM) and `platform.cljs` (CLJS).
+- Sqids algorithm logic is implemented in-repo (`alphabet.cljc`, `encoding.cljc`, `decoding.cljc`, `block_list.cljc`, `init.cljc`).
+- Bundled data assets are in `resources/` (for example `resources/org/sqids/clojure/blocklist.json`).
+- Tests are under `test/org/sqids/clojure/*_test.cljc`.
+- Tooling scripts are in `bin/` (`setup`, `kaocha`, `repl`, `_clj-kondo`, `_cljstyle`, `update-blocklist`).
+
+## Build, Test, and Development Commands
+
+- `bin/setup`: installs local prerequisites (`brew bundle`, `npm install`) on macOS/Homebrew setups.
+- `bin/kaocha`: runs all Kaocha suites (JVM `clojure.test`, automatic `clojure.spec.test.check`, and CLJS) with coverage output in `target/coverage/` and JUnit XML in `target/test-results/junit.xml`.
+- `bin/repl clj` / `bin/repl cljs`: starts interactive REPLs.
+- `bin/update-blocklist`: refreshes `resources/org/sqids/clojure/blocklist.json` from `sqids-spec`.
+- `pre-commit run --all-files`: runs local hooks; CI mirrors this as `SKIP=kaocha-test pre-commit run --all-files` followed by `bin/kaocha`.
+- `clojure -T:build jar` and `clojure -T:build install`: build and install the jar locally.
+
+## Project Patterns
+
+- Treat `AGENTS.md` as a repo table of contents, not an encyclopedia: point to the system-of-record files for behavior, build, tests, lint, and generated data before adding new prose here.
+- Prefer checked-in repo knowledge over chat or PR context; if code, tests, and docs disagree, the repository wins and stale guidance should be fixed in the same change.
+- Treat `bin/kaocha` as the single test entrypoint for local runs, pre-commit, and CI; avoid re-introducing split CLJ/CLJS wrappers.
+- Keep `tests.edn` as the source of truth for suite and report behavior (`:unit`, `:cljs`, `:generative-fdef-checks`, cloverage, JUnit XML target).
+- Keep test automation in sync: when pre-commit hook IDs or test commands change, update `.github/workflows/clojure.yml` (`SKIP=...`) in the same commit.
+- Prefer local/system hooks and wrappers over Docker hooks (`clj-kondo`, `cljstyle`, `shfmt`, `prettier`); avoid adding Docker-based hook runners.
+- Move invariants into mechanical enforcement whenever possible; prefer `clj-kondo`, `cljstyle`, pre-commit, Kaocha, and CI checks over reviewer memory or PR prose.
+- Keep algorithm code total in internal namespaces: only public `org.sqids.clojure/{sqids,encode,decode}` should throw.
+- Model internal success/failure with `org.sqids.clojure.results` envelopes and staged `results/conform`, `results/bind`, `results/attempt` pipelines.
+- Keep tool versions pinned in project config (`deps.edn`, `.pre-commit-config.yaml`); CI may use `latest` for bootstrap tools, but lint/format/test versions should remain explicit.
+- Treat `resources/org/sqids/clojure/blocklist.json` as generated data; update it via `bin/update-blocklist` rather than manual edits.
+- Add nested `AGENTS.md` files only when a subtree has materially different rules or maintenance needs; keep them short, additive, and scoped to local deltas rather than copying the root guide.
+- Pair every `AGENTS.md` with a human-facing `README.md` in the same scope. `AGENTS.md` directs agent behavior; `README.md` explains layout, intent, and workflows for humans.
+- When adding a new subsystem, ship code, tests, lint/config enforcement, docstrings, and navigation docs together.
+- Keep docs aligned with tooling changes: update `README.md` and this file in the same PR when commands or test flow change.
+- When behavior changes, update tests, docstrings, and README examples in the same commit so the contract stays synchronized.
+- Preserve public API behavior for `sqids`, `encode`, and `decode`; behavior changes must include deterministic tests and release notes updates.
+
+## Coding Style & Naming Conventions
+
+- Follow `.cljstyle`: 2-space indentation and one blank padding line between top-level forms.
+- Run formatting before commits: `bin/_cljstyle fix`.
+- Lint with pre-commit (includes `clj-kondo`, `cljstyle`, `kaocha-test`, `shellcheck`, `shfmt`, `markdownlint-cli2`, `prettier`, and a clean `git-diff` check).
+- `clj-kondo` is intentionally strict in `.clj-kondo/config.edn`; run `bin/_clj-kondo --lint src test bin/update-blocklist build.clj deps.edn tests.edn shadow-cljs.edn` before pushing.
+- Every `def`, `defn`, and `defmacro` needs a high-quality docstring. Treat docstrings as living contracts: explain purpose, inputs, return shape, invariants, and failure semantics when they are not obvious from the name alone.
+- Keep docstring enforcement strict. If `clj-kondo` stops catching missing docstrings on new function-like forms, tighten the linter or hooks instead of weakening the rule.
+- Namespace/file naming follows Clojure conventions: `kebab-case` namespaces and `*_test.cljc` test files.
+
+## Testing Guidelines
+
+- Primary framework: `clojure.test` executed by Kaocha; generative spec checks run via a `:kaocha.type/spec.test.check` suite.
+- Coverage is enforced at 100% via `:cloverage/opts :fail-threshold`; CI artifacts include `target/coverage/lcov.info` and `target/coverage/codecov.json`.
+- Add tests beside related behavior in `test/org/sqids/clojure/`.
+- Keep tests deterministic and cover both encode/decode behavior and invalid-input paths.
+- Before opening a PR, run `bin/kaocha`.
+
+## Commit & Pull Request Guidelines
+
+- Match existing history: short, imperative commit subjects (for example `Fix sqids-javascript link`, `Improve caching`).
+- Keep commits focused; separate refactors from behavior changes when possible.
+- PRs should include: purpose, key changes, and verification steps/commands run.
+- Link relevant issues when applicable and update `CHANGELOG.md` for release-facing changes.

Brewfile

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 tap 'borkdude/brew'
+tap 'babashka/brew'
 
 brew 'borkdude/brew/clj-kondo'
+brew 'babashka/brew/babashka'
 brew 'clojure'
 brew 'pre-commit'
 

CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
-**v1.0.15**:
+## Unreleased
+
+## v1.1.0
+
+- Replaced external runtime wrappers with a shared pure Clojure/ClojureScript
+  Sqids implementation.
+- Added a local default blocklist resource and expanded spec-alignment tests.
+- Updated contributor/development documentation and script usage text.
+
+## v1.0.15
 
 - Initial implementation