{"id":15873902,"url":"https://github.com/wavejumper/boonmee","last_synced_at":"2025-03-16T04:30:47.863Z","repository":{"id":62435125,"uuid":"279040811","full_name":"wavejumper/boonmee","owner":"wavejumper","description":"A Clojure language server (WIP)","archived":false,"fork":false,"pushed_at":"2020-07-25T03:09:03.000Z","size":214,"stargazers_count":7,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-27T05:03:33.314Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wavejumper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-12T10:25:27.000Z","updated_at":"2022-07-29T11:39:14.000Z","dependencies_parsed_at":"2022-11-01T21:02:40.568Z","dependency_job_id":null,"html_url":"https://github.com/wavejumper/boonmee","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavejumper%2Fboonmee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavejumper%2Fboonmee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavejumper%2Fboonmee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavejumper%2Fboonmee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wavejumper","download_url":"https://codeload.github.com/wavejumper/boonmee/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243802944,"owners_count":20350316,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-06T01:08:13.849Z","updated_at":"2025-03-16T04:30:47.155Z","avatar_url":"https://github.com/wavejumper.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Clojure CI](https://github.com/wavejumper/boonmee/workflows/Clojure%20CI/badge.svg?branch=master)\n![Release](https://github.com/wavejumper/boonmee/workflows/Release/badge.svg?branch=master)\n[![Clojars Project](https://img.shields.io/clojars/v/wavejumper/boonmee.svg)](https://clojars.org/wavejumper/boonmee)\n\n# boonmee\n\nboonmee is a language server for Clojure that focuses on features relating to host interop.\n\nIt is an attempt to bring first-class 'intellisense' to ClojureScript projects.\n\nGoals:\n\n* For now, focus on interop - there are other great tools that lint Clojure code already ([clj-kondo](https://github.com/borkdude/clj-kondo), [joker](https://github.com/candid82/joker) etc)\n* Tooling-agnostic - you should be able to integrate boonmee into any IDE/editor tool\n* All analysis should be static, and side-effect free (eg, does not evaluate any code)\n\nRight now boonmee only works on ClojureScript code (my personal frustration), but there are plans to target the JVM as well.\n\nYou can read [this](https://tscrowley.dev/#/posts/2020-20-07-boonmee) blog post about boonmee and its implementation details.\n\n## Why\n\nThe biggest strength of Clojure is the fact that it is a hosted language.\n\nEvery Clojure codebase I have worked on leverages a host library at its core. \n\nAnd yet, most linting/editor tools (outside of Cursive for the JVM) consider the host language as an afterthought.\n\n## Features\n\n### Editor functionality:\n\n- [x] Quickinfo ([@jsdoc](https://jsdoc.app/) documentation, type signature, fn metadata etc)\n- [x] Code completions (require, fn calls)\n- [x] Code navigation (jump to definition)\n\n### Linting (WIP):\n\n- [ ] Warn on deprecated methods (via @jsdoc convention)\n- [ ] Warn on undefined es6 method call\n- [ ] Incorrect arity on es6 method call\n- [ ] Basic type-checking\n\n## Installation\n\nDownload a binary from the [releases](https://github.com/wavejumper/boonmee/releases) page. \n\nBinaries get built via [GitHub Actions](https://github.com/wavejumper/boonmee/actions)\n\nRefer to the [CI job](https://github.com/wavejumper/boonmee/blob/master/.github/workflows/release.yml) on how to compile boonmee as a native image from source.\n\n## Dependencies \n\nboonmee requires [NodeJS](https://nodejs.org/en/), and the TypeScript standalone server (`tsserver`):\n\n```\nnpm install -g typescript\n```\n\nBy default, boonmee will use the `tsserver` found on your `$PATH`. However, you can also specify a custom path:\n\n```\n./boonmee --tsserver=/path/to/tsserver\n````\n\n## Usage\n\nInteraction with boonmee happens via stdio:\n\n`./boonmee`\n\nRefer to the [Example RPC](#example-rpc) section for some examples of client requests.\n\nIf you would like to use boonmee directly from a Clojure project, bring in the following dependency:\n\n```clojure\n[wavejumper/boonmee \"0.1.0-alpha2\"]\n```\n\n```clojure\n(require '[boonmee.client.clojure :as boonmee])\n(require '[clojure.core.async :as async])\n\n(def client (boonmee/client {}))\n\n(async/put! (:req-ch client) {}) ;; Make a request\n(async/\u003c!! (:resp-ch client)) ;; Wait until there is a response...\n(boonmee/stop client)\n```\n\n## Editor integration\n\n### Emacs (WIP)\n\n![emacs plugin](https://i.imgur.com/9FVeVn5.gif)\n\nSee [boonmee.el](https://github.com/wavejumper/boonmee/blob/master/clients/emacs/boonmee.el) in this repo\n\nWIP emacs client, currently supports:\n\n- [x] Quickinfo (`M-x boonmee-quickinfo`)\n- [ ] Code completions\n- [x] Code navigation (`M-x boonmee-goto-definition`)\n\nIn your `init.el`, add something like:\n\n```emacs-lisp\n(add-hook 'clojure-mode-hook (lambda() (boonmee-mode t)))\n```\n\n## ClojureScript \n\n### NPM deps\n\nNote: boonmee analyses NPM dependencies found in a `node_modules` directory at your project's root. \n\nIf you rely on cljsjs packages you're out of luck.\n\nIf you are a [shadow-cljs](http://shadow-cljs.org/) user, using boonmee should be a seamless experience.\n\n### @types\n\nboonmee's functionality comes from the [TypeScript](https://www.typescriptlang.org/) compiler. \n\nThat means a `@types/*` package should be installed as a dev dependency, if the library you require is written in vanilla JavaScript:\n\n```\nnpm install --save-dev @types/react\n```\n\nThe [DefinitelyTyped/DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) repo has many type definitions for popular npm dependencies.\n\n**TODO**: infer/suggest possible `@types/` stubs.\n\n### Globals\n\nThe `--env` switch tells boonmee which environment your ClojureScript project is targeting. \n\nThis enables intellisense for `js/...` globals. \n\nOptions are: `browser` (default) or `node`.\n\n``` \n./boonmee --env=node\n```\n\n**Note** for the `node` env you will also need to `npm install --save-dev @types/node`\n\n## Protocol\n\nSpecs for the boonmee protocol can be found in the [boonmee.protocol](https://github.com/wavejumper/boonmee/blob/master/src/boonmee/protocol.clj) namespace.\n\n## Example RPC\n\nHere's our example Clojure source code:\n\n```clojure \n(ns tonal.core\n  (:require [\"@tonaljs/tonal\" :refer [Midi]]))\n\n(Midi/m ) ;; [4 7], left incomplete for our completions example\n\n\n(Midi/midiToFreq 400) ;; [7 10], for our quickinfo and definitions example\n```\n\nExamples relate to the [tonaljs](https://github.com/tonaljs/tonal/blob/master/packages/midi/index.ts) npm package\n\nFor more examples, refer to boonmee's [integration tests](https://github.com/wavejumper/boonmee/tree/master/test/boonmee/integration)\n\n### Completions\n\n#### Request\n\n```javascript \n{\n  \"command\": \"completions\",\n  \"type\": \"request\",\n  \"requestId\": \"12345\",\n  \"arguments\": {\n    \"projectRoot\": \"/path/to/project/root\",\n    \"file\": \"/path/to/core.cljs\",\n    \"line\": 4,\n    \"offset\": 7\n  }\n}\n```\n\n#### Response\n\n```javascript\n{\n  \"command\": \"completionInfo\",\n  \"type\": \"response\",\n  \"success\": true,\n  \"interop\": {\n    \"fragments\": [\n      \"m\"\n    ],\n    \"isGlobal\": false,\n    \"prevLocation\": [\n      4,\n      1\n    ],\n    \"nextLocation\": [\n      7,\n      1\n    ],\n    \"sym\": \"Midi\",\n    \"usage\": \"method\"\n  },\n  \"data\": {\n    \"isGlobalCompletion\": false,\n    \"isMemberCompletion\": true,\n    \"isNewIdentifierLocation\": false,\n    \"entries\": [\n      {\n        \"name\": \"freqToMidi\",\n        \"kind\": \"property\",\n        \"kindModifiers\": \"declare\",\n        \"sortText\": \"0\"\n      },\n      {\n        \"name\": \"isMidi\",\n        \"kind\": \"property\",\n        \"kindModifiers\": \"declare\",\n        \"sortText\": \"0\"\n      },\n      {\n        \"name\": \"midiToFreq\",\n        \"kind\": \"property\",\n        \"kindModifiers\": \"declare\",\n        \"sortText\": \"0\"\n      },\n      {\n        \"name\": \"midiToNoteName\",\n        \"kind\": \"property\",\n        \"kindModifiers\": \"declare\",\n        \"sortText\": \"0\"\n      },\n      {\n        \"name\": \"toMidi\",\n        \"kind\": \"property\",\n        \"kindModifiers\": \"declare\",\n        \"sortText\": \"0\"\n      }\n    ]\n  },\n  \"requestId\": \"12345\"\n}\n```\n\n### Quickinfo\n\n#### Request\n\n```javascript \n{\n  \"command\": \"quickinfo\",\n  \"type\": \"request\",\n  \"requestId\": \"12345\",\n  \"arguments\": {\n    \"file\": \"/path/to/core.cljs\",\n    \"projectRoot\": \"/path/to/root\",\n    \"line\": 7,\n    \"offset\": 10\n  }\n}\n```\n\n#### Response\n\n```javascript\n{\n  \"command\": \"quickinfo\",\n  \"type\": \"response\",\n  \"success\": true,\n  \"data\": {\n    \"kind\": \"property\",\n    \"kindModifiers\": \"declare\",\n    \"displayString\": \"(property) midiToFreq: (midi: number, tuning?: number) =\u003e number\",\n    \"documentation\": \"\",\n    \"tags\": []\n  },\n  \"interop\": {\n    \"fragments\": [\n      \"midiToFreq\"\n    ],\n    \"sym\": \"Midi\",\n    \"isGlobal\": false,\n    \"usage\": \"method\",\n    \"prevLocation\": [\n      7,\n      1\n    ],\n    \"nextLocation\": [\n      7,\n      18\n    ]\n  },\n  \"requestId\": \"12345\"\n}\n```\n\n### Definitions\n\n#### Request\n\n```javascript \n{\n  \"command\": \"definition\",\n  \"type\": \"request\",\n  \"requestId\": \"12345\",\n  \"arguments\": {\n    \"file\": \"/path/to/core/core.cljs\",\n    \"projectRoot\": \"/path/to/project/root\",\n    \"line\": 7,\n    \"offset\": 10\n  }\n}\n```\n\n#### Response\n\n```javascript\n{\n  \"command\": \"definition\",\n  \"data\": {\n    \"contextEnd\": {\n      \"line\": 69,\n      \"offset\": 35\n    },\n    \"contextStart\": {\n      \"line\": 69,\n      \"offset\": 5\n    },\n    \"end\": {\n      \"line\": 69,\n      \"offset\": 15\n    },\n    \"file\": \"/path/to/tonal/node_modules/@tonaljs/midi/dist/index.d.ts\",\n    \"start\": {\n      \"line\": 69,\n      \"offset\": 5\n    }\n  },\n  \"interop\": {\n    \"fragments\": [\n      \"midiToFreq\"\n    ],\n    \"isGlobal\": false,\n    \"nextLocation\": [\n      7,\n      18\n    ],\n    \"prevLocation\": [\n      7,\n      1\n    ],\n    \"sym\": \"Midi\",\n    \"usage\": \"method\"\n  },\n  \"requestId\": \"12345\",\n  \"success\": true,\n  \"type\": \"response\"\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavejumper%2Fboonmee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwavejumper%2Fboonmee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavejumper%2Fboonmee/lists"}