js-qualified-keywords 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 clojure-keywords-js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# js-qualified-keywords
+
+Clojure-style qualified keywords (`:ns/name`) as a first-class data type in JavaScript.
+
+```js
+const status = :active;
+const schema = {
+  [:user/name]:  { type: 'string' },
+  [:user/email]: { type: 'string' },
+};
+```
+
+## Install
+
+```bash
+npm install js-qualified-keywords
+```
+
+## Runtime
+
+```js
+const { kw, Keyword, KeywordMap } = require('js-qualified-keywords');
+
+const k = kw('user', 'name');
+k.ns        // "user"
+k.name      // "name"
+k.fqn       // "user/name"
+k.toString() // ":user/name"
+
+// Interned — same args, same instance
+kw('user', 'name') === kw('user', 'name') // true
+
+// Parse from string
+Keyword.of(':user/name')  // same as kw('user', 'name')
+
+// KeywordMap: like Map but keyed by keyword identity
+const m = new KeywordMap();
+m.set(kw('user', 'name'), 'Alice');
+m.get(kw('user', 'name'))  // "Alice"
+m.get(':user/name')        // "Alice" — string keys work too
+
+KeywordMap.fromObject({ ':user/name': 'Alice' })  // build from plain object
+m.toObject()                                       // back to plain object
+```
+
+## Babel Plugin
+
+Transforms `:ns/name` syntax into runtime calls so you can write keywords directly in `.js` files.
+
+**.babelrc**
+```json
+{ "plugins": ["js-qualified-keywords/babel-plugin"] }
+```
+
+Input:
+```js
+const x = :user/name;
+const o = { [:db/id]: 1 };
+```
+
+Output:
+```js
+const { kw: _kw } = require('js-qualified-keywords/runtime');
+const x = _kw('user', 'name');
+const o = { [_kw('db', 'id')]: 1 };
+```
+
+Keywords inside strings and comments are left untouched. The ternary `: ` is not mistaken for a keyword.
+
+## LSP Server
+
+Provides completion, hover, go-to-definition, find-references, rename, and diagnostics for keyword literals in JS/TS files.
+
+```bash
+cd lsp-server && npm install
+node lsp-server/server.js --stdio
+```
+
+Point your editor's LSP client at that command, scoped to `javascript`, `javascriptreact`, `typescript`, `typescriptreact`.
+
+## Emacs (lsp-mode)
+
+**1. Install server dependencies (once):**
+```bash
+cd lsp-server && npm install
+```
+
+**2. Add to your `init.el` / config:**
+```elisp
+(setq js-qualified-keywords-lsp-server-dir "/path/to/js-qualified-keywords/lsp-server")
+(load "/path/to/js-qualified-keywords/editors/emacs/js-qualified-keywords-lsp.el")
+(add-hook 'js-mode-hook #'lsp)   ; skip if lsp already starts automatically
+```
+
+**3. Open any `.js` file** — lsp-mode connects automatically.
+
+| Feature | Key |
+|---|---|
+| Hover | `K` |
+| Completion | type `:` or `:ns/` |
+| Go to definition | `M-.` |
+| Find references | `M-?` |
+| Rename | `C-c l r r` |
+| Server status | `M-x lsp-describe-session` |
+
+If the server doesn't connect, check the `*lsp-log*` buffer. Most common cause: `node` not on Emacs's `exec-path` — fix with `(add-to-list 'exec-path "/usr/local/bin")`.
+
+If you run multiple LSP servers on JS files (e.g. `ts-ls`), both activate independently. To make js-qualified-keywords take priority, raise `:priority` above `-1` in the `.el` file.
+
+## VS Code Extension
+
+Bundles the LSP server as a VS Code extension.
+
+```bash
+cd vscode-extension && npm install
+# Press F5 in VS Code to launch the Extension Development Host
+```
+
+To package for distribution:
+```bash
+npx vsce package
+```
+
+## Conventions
+
+| Style | Example | Use for |
+|---|---|---|
+| Qualified | `:user/name` | domain attributes, schema keys |
+| Simple | `:active` | enums, flags, modes |
+
+Use `.kw.js` as the file extension to signal that a file contains keyword syntax (optional, helps tooling).
+
+## Publishing to npm
+
+```bash
+# 1. Check the name is free
+npm info js-qualified-keywords
+# If taken, use a scoped name: change "name" in package.json to "@yourname/js-qualified-keywords"
+
+# 2. Log in (create an account at npmjs.com first if needed)
+npm login
+
+# 3. Publish
+npm publish                   # unscoped package
+npm publish --access public   # scoped package (@yourname/...)
+```
+
+Future releases:
+```bash
+npm version patch   # 0.1.0 → 0.1.1
+npm version minor   # 0.1.0 → 0.2.0
+npm publish
+```
+
+Before publishing, update the `homepage`, `bugs`, and `repository` URLs in `package.json` to point to your actual repo.
+
+## Limitations
+
+- **Source maps**: The Babel plugin pre-processes source text before parsing, which changes string lengths (`:user/name` becomes `_kw("user", "name")`). Babel's source maps are generated from the transformed source, so column offsets may be slightly off. Line numbers remain correct.
+- No TypeScript type-level support yet.

package/babel-plugin/index.js

@@ -0,0 +1,115 @@
+/**
+ * babel-plugin-js-qualified-keywords
+ *
+ * Transforms Clojure-style keyword syntax in JavaScript:
+ *
+ *   :user/name   →  _kw("user", "name")
+ *   :db/id       →  _kw("db", "id")
+ *   :active      →  _kw(null, "active")
+ *
+ * Strategy:
+ * 1. Pre-process source to replace keyword literals with `_kw(...)` calls
+ *    before Babel's parser sees the code.
+ * 2. Babel handles the resulting AST normally.
+ * 3. A `require("js-qualified-keywords/runtime")` import is injected when needed.
+ *
+ * The scanner logic (strings, comments, template literals, regex literals)
+ * is shared with lib/scan.js via `walkCode` — one state machine, two
+ * consumers.
+ *
+ * NOTE: Source maps will have slightly wrong column offsets because the
+ * preprocessing changes string lengths before Babel sees the source.
+ *
+ * Usage in .babelrc:
+ *   { "plugins": ["js-qualified-keywords/babel-plugin"] }
+ */
+
+const { KEYWORD_RE, BEFORE_KW_RE, walkCode } = require('../lib/scan');
+
+/**
+ * Pre-process source code, replacing keyword literals outside strings,
+ * comments, template string parts, and regex literals with `_kw(...)` calls.
+ *
+ * @param {string} code
+ * @returns {string}
+ */
+function preprocess(code) {
+  // Pass 1: collect code-context positions.
+  const codeSet = new Set();
+  walkCode(code, (i) => codeSet.add(i));
+
+  // Pass 2: walk source, replacing keywords at code positions.
+  const result = [];
+  let i = 0;
+
+  while (i < code.length) {
+    if (!codeSet.has(i)) {
+      // Not in code context — copy verbatim.
+      result.push(code[i++]);
+      continue;
+    }
+
+    if (code[i] === ':') {
+      const before = i > 0 ? code[i - 1] : ' ';
+      if (i === 0 || BEFORE_KW_RE.test(before)) {
+        KEYWORD_RE.lastIndex = i;
+        const match = KEYWORD_RE.exec(code);
+        if (match && match.index === i) {
+          const ns = match[2] ? match[1] : null;
+          const name = match[2] || match[1];
+          result.push(ns ? `_kw("${ns}", "${name}")` : `_kw(null, "${name}")`);
+          i += match[0].length;
+          continue;
+        }
+      }
+    }
+
+    result.push(code[i++]);
+  }
+
+  return result.join('');
+}
+
+/**
+ * Babel plugin entry point.
+ */
+function clojureKeywordsPlugin({ types: t }) {
+  return {
+    name: 'js-qualified-keywords',
+
+    parserOverride(code, opts, parse) {
+      const processed = preprocess(code);
+      // Store whether this file needs the import on the opts object
+      // so it's per-file, not per-session.
+      opts.__clojureKeywordsNeedsImport = processed !== code;
+      return parse(processed, opts);
+    },
+
+    visitor: {
+      Program: {
+        exit(path, state) {
+          const hasKw = path.scope.hasGlobal('_kw');
+          const needsImport = state.opts.__clojureKeywordsNeedsImport;
+          if (!hasKw && !needsImport) return;
+
+          // const { kw: _kw } = require("js-qualified-keywords/runtime");
+          const importDecl = t.variableDeclaration('const', [
+            t.variableDeclarator(
+              t.objectPattern([
+                t.objectProperty(t.identifier('kw'), t.identifier('_kw')),
+              ]),
+              t.callExpression(t.identifier('require'), [
+                t.stringLiteral('js-qualified-keywords/runtime'),
+              ])
+            ),
+          ]);
+
+          path.unshiftContainer('body', importDecl);
+        },
+      },
+    },
+  };
+}
+
+clojureKeywordsPlugin.preprocess = preprocess;
+module.exports = clojureKeywordsPlugin;

package/lib/scan.js

@@ -0,0 +1,227 @@
+/**
+ * Stack-based JavaScript source scanner.
+ *
+ * Correctly skips strings (single, double, template string parts),
+ * comments, and regex literals — including arbitrarily nested template
+ * literals.
+ *
+ * Shared by both the Babel plugin and the LSP server so they operate on
+ * identical tokenization rules.
+ */
+
+// ─── Shared regexes ───────────────────────────────────────────────────
+
+/** Matches a keyword literal starting at position lastIndex. */
+const KEYWORD_RE = /:([a-zA-Z_][\w.-]*)(?:\/([a-zA-Z_][\w.-]*))?/g;
+
+/** Characters that can legitimately appear immediately before a keyword. */
+const BEFORE_KW_RE = /[\s\[({,;=!&|?:><%+\-^~]/;
+
+/**
+ * Characters that, when they precede a `/`, indicate the start of a
+ * regex literal rather than a division operator.
+ *
+ * This is the standard heuristic used by linters and syntax highlighters:
+ * a `/` is a regex when preceded by an operator, punctuator, or keyword
+ * boundary — NOT by an identifier, number, or closing bracket.
+ */
+const REGEX_PREDECESSOR_RE = /[=!({[,;:?&|^~+\-*/%<>]\s*$/;
+
+// ─── Low-level scanner ───────────────────────────────────────────────
+
+/**
+ * Walk `source` character-by-character, calling `onCode(i)` for every
+ * character that falls in "code context" (where keyword literals can
+ * appear).  Characters inside strings, comments, template string parts,
+ * and regex literals are skipped.
+ *
+ * Returns nothing — side-effects happen through `onCode`.
+ *
+ * @param {string}       source
+ * @param {(i: number) => void} onCode
+ */
+function walkCode(source, onCode) {
+  let i = 0;
+
+  // Stack: 'code' | 'template' | 'template-expr'
+  const stack = ['code'];
+  // Parallel to 'template-expr' frames: tracks inner { } depth.
+  const exprDepth = [];
+
+  while (i < source.length) {
+    const ctx = stack[stack.length - 1];
+
+    // ── Template string part — skip verbatim ─────────────────────────
+    if (ctx === 'template') {
+      if (source[i] === '\\') { i += 2; continue; }
+      if (source[i] === '`') { stack.pop(); i++; continue; }
+      if (source[i] === '$' && source[i + 1] === '{') {
+        stack.push('template-expr');
+        exprDepth.push(0);
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+
+    // ── Code / template-expr ─────────────────────────────────────────
+
+    // Single-line comment
+    if (source[i] === '/' && source[i + 1] === '/') {
+      const end = source.indexOf('\n', i);
+      i = end === -1 ? source.length : end;
+      continue;
+    }
+
+    // Multi-line comment
+    if (source[i] === '/' && source[i + 1] === '*') {
+      const end = source.indexOf('*/', i + 2);
+      i = end === -1 ? source.length : end + 2;
+      continue;
+    }
+
+    // Regex literal — must come before the `/` is treated as code.
+    // We use a preceding-context heuristic: if the text before `/`
+    // ends with an operator/punctuator, this is a regex, not division.
+    if (source[i] === '/' && source[i + 1] !== '/' && source[i + 1] !== '*') {
+      const preceding = source.slice(Math.max(0, i - 20), i);
+      if (i === 0 || REGEX_PREDECESSOR_RE.test(preceding)) {
+        // Skip the regex body.
+        let j = i + 1;
+        while (j < source.length) {
+          if (source[j] === '\\') { j += 2; continue; }
+          if (source[j] === '/') { j++; break; }
+          if (source[j] === '[') {
+            // Character class — skip until ]
+            j++;
+            while (j < source.length) {
+              if (source[j] === '\\') { j += 2; continue; }
+              if (source[j] === ']') { j++; break; }
+              j++;
+            }
+            continue;
+          }
+          j++;
+        }
+        // Skip regex flags (gimsuvy)
+        while (j < source.length && /[gimsuvyd]/.test(source[j])) j++;
+        i = j;
+        continue;
+      }
+    }
+
+    // Single / double quoted string
+    if (source[i] === '"' || source[i] === "'") {
+      const quote = source[i++];
+      while (i < source.length) {
+        if (source[i] === '\\') { i += 2; continue; }
+        if (source[i] === quote) { i++; break; }
+        i++;
+      }
+      continue;
+    }
+
+    // Template literal start
+    if (source[i] === '`') {
+      stack.push('template');
+      i++;
+      continue;
+    }
+
+    // Brace tracking inside template expression
+    if (ctx === 'template-expr') {
+      if (source[i] === '{') { exprDepth[exprDepth.length - 1]++; onCode(i); i++; continue; }
+      if (source[i] === '}') {
+        if (exprDepth[exprDepth.length - 1] === 0) { exprDepth.pop(); stack.pop(); }
+        else { exprDepth[exprDepth.length - 1]--; onCode(i); }
+        i++;
+        continue;
+      }
+    }
+
+    onCode(i);
+    i++;
+  }
+}
+
+// ─── scanKeywords ─────────────────────────────────────────────────────
+
+/**
+ * Scan JS source for keyword literals, returning their positions.
+ *
+ * @param {string} source
+ * @returns {Array<{ns: string|null, name: string, fqn: string, index: number, length: number}>}
+ */
+function scanKeywords(source) {
+  const results = [];
+  const codePositions = new Set();
+
+  walkCode(source, (i) => codePositions.add(i));
+
+  // Now walk code positions looking for keyword starts.
+  for (const i of codePositions) {
+    if (source[i] !== ':') continue;
+
+    const before = i > 0 ? source[i - 1] : ' ';
+    if (i !== 0 && !BEFORE_KW_RE.test(before)) continue;
+
+    KEYWORD_RE.lastIndex = i;
+    const match = KEYWORD_RE.exec(source);
+    if (!match || match.index !== i) continue;
+
+    const ns = match[2] ? match[1] : null;
+    const name = match[2] || match[1];
+    results.push({
+      ns, name,
+      fqn: ns ? `${ns}/${name}` : name,
+      index: i,
+      length: match[0].length,
+    });
+  }
+
+  return results;
+}
+
+// ─── Position helpers ─────────────────────────────────────────────────
+
+/**
+ * Build an array of character offsets, one per line.
+ * lineOffsets[n] is the index of the first character on line n.
+ *
+ * @param {string} text
+ * @returns {number[]}
+ */
+function computeLineOffsets(text) {
+  const offsets = [0];
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '\n') offsets.push(i + 1);
+  }
+  return offsets;
+}
+
+/**
+ * Convert a character offset to a { line, character } LSP position.
+ *
+ * @param {number[]} lineOffsets
+ * @param {number} offset
+ * @returns {{ line: number, character: number }}
+ */
+function offsetToPosition(lineOffsets, offset) {
+  let low = 0, high = lineOffsets.length - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (lineOffsets[mid] <= offset) low = mid;
+    else high = mid - 1;
+  }
+  return { line: low, character: offset - lineOffsets[low] };
+}
+
+module.exports = {
+  KEYWORD_RE,
+  BEFORE_KW_RE,
+  walkCode,
+  scanKeywords,
+  computeLineOffsets,
+  offsetToPosition,
+};

package/lsp-server/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "js-qualified-keywords-lsp",
+  "version": "0.1.0",
+  "description": "LSP server for Clojure-style keywords in JavaScript",
+  "private": true,
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js --stdio"
+  },
+  "dependencies": {
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.11"
+  }
+}

package/lsp-server/server.js

@@ -0,0 +1,360 @@
+/**
+ * LSP Server for Clojure-style Keywords in JavaScript.
+ *
+ * Features:
+ *   - Completion   — type `:` to see known keywords; `:ns/` to filter by namespace
+ *   - Hover        — shows namespace, name, and usage count
+ *   - Definition   — jumps to first occurrence
+ *   - References   — all usages across the workspace
+ *   - Rename       — rename a keyword everywhere
+ *   - Diagnostics  — hints for keywords used only once (possible typo)
+ */
+
+const {
+  createConnection,
+  TextDocuments,
+  ProposedFeatures,
+  CompletionItemKind,
+  DiagnosticSeverity,
+  TextDocumentSyncKind,
+  MarkupKind,
+} = require('vscode-languageserver/node');
+const { TextDocument } = require('vscode-languageserver-textdocument');
+const { scanKeywords, computeLineOffsets, offsetToPosition } = require('../lib/scan');
+
+const connection = createConnection(ProposedFeatures.all);
+const documents = new TextDocuments(TextDocument);
+
+// ─── Keyword Index ────────────────────────────────────────────────────
+
+/** @type {Map<string, Array<{uri:string, line:number, character:number, endCharacter:number}>>} */
+const keywordIndex = new Map();
+
+/** @type {Map<string, Set<string>>} namespace -> set of names */
+const namespaceIndex = new Map();
+
+/**
+ * Per-document scan cache.  Avoids re-scanning the full document on every
+ * hover / definition / references / rename request.
+ * @type {Map<string, {version: number, keywords: Array<{ns:string|null, name:string, fqn:string, index:number, length:number}>, lineOffsets: number[]}>}
+ */
+const docCache = new Map();
+
+function indexDocument(doc) {
+  const uri = doc.uri;
+  const text = doc.getText();
+
+  const keywords = scanKeywords(text);
+  const lineOffsets = computeLineOffsets(text);
+
+  // Cache scan results so getKeywordAtPosition / validateDocument don't re-scan.
+  docCache.set(uri, { version: doc.version, keywords, lineOffsets });
+
+  // Remove stale entries for this file.
+  for (const [fqn, locs] of keywordIndex) {
+    const filtered = locs.filter(l => l.uri !== uri);
+    if (filtered.length === 0) keywordIndex.delete(fqn);
+    else keywordIndex.set(fqn, filtered);
+  }
+
+  // Insert new entries.
+  for (const { ns, name, fqn, index, length } of keywords) {
+    const { line, character } = offsetToPosition(lineOffsets, index);
+    const loc = { uri, line, character, endCharacter: character + length };
+
+    if (!keywordIndex.has(fqn)) keywordIndex.set(fqn, []);
+    keywordIndex.get(fqn).push(loc);
+  }
+
+  // Rebuild namespaceIndex from scratch (avoids ghost namespaces).
+  namespaceIndex.clear();
+  for (const [fqn] of keywordIndex) {
+    const slashIdx = fqn.indexOf('/');
+    if (slashIdx !== -1) {
+      const ns = fqn.slice(0, slashIdx);
+      const name = fqn.slice(slashIdx + 1);
+      if (!namespaceIndex.has(ns)) namespaceIndex.set(ns, new Set());
+      namespaceIndex.get(ns).add(name);
+    }
+  }
+}
+
+/**
+ * Find the keyword that covers `position` in `doc`, if any.
+ * Uses the cached scan results from indexDocument.
+ */
+function getKeywordAtPosition(doc, position) {
+  const cache = docCache.get(doc.uri);
+  if (!cache) return null;
+
+  const { keywords, lineOffsets } = cache;
+  const offset = lineOffsets[position.line] + position.character;
+
+  for (const kw of keywords) {
+    if (offset >= kw.index && offset <= kw.index + kw.length) {
+      const lineStart = lineOffsets[position.line];
+      return {
+        ns: kw.ns,
+        name: kw.name,
+        fqn: kw.fqn,
+        start: kw.index - lineStart,
+        end: kw.index + kw.length - lineStart,
+      };
+    }
+  }
+  return null;
+}
+
+// ─── LSP Capabilities ─────────────────────────────────────────────────
+
+connection.onInitialize(() => ({
+  capabilities: {
+    textDocumentSync: TextDocumentSyncKind.Incremental,
+    completionProvider: { triggerCharacters: [':', '/'], resolveProvider: false },
+    hoverProvider: true,
+    definitionProvider: true,
+    referencesProvider: true,
+    renameProvider: { prepareProvider: true },
+  },
+}));
+
+// ─── Document Sync ────────────────────────────────────────────────────
+
+documents.onDidChangeContent(({ document }) => {
+  indexDocument(document);
+  validateDocument(document);
+});
+
+documents.onDidClose(({ document }) => {
+  docCache.delete(document.uri);
+});
+
+// ─── Completion ───────────────────────────────────────────────────────
+
+connection.onCompletion(({ textDocument, position }) => {
+  const doc = documents.get(textDocument.uri);
+  if (!doc) return [];
+
+  const lineText = doc.getText({
+    start: { line: position.line, character: 0 },
+    end: { line: position.line, character: position.character },
+  });
+
+  const kwMatch = lineText.match(/:([\w.-]*(?:\/[\w.-]*)?)$/);
+  if (!kwMatch) return [];
+
+  const partial = kwMatch[1];
+  const replaceStart = position.character - kwMatch[0].length; // includes the ':'
+  const items = [];
+
+  if (partial.includes('/')) {
+    const [nsPrefix, namePrefix] = partial.split('/', 2);
+    const names = namespaceIndex.get(nsPrefix);
+    if (names) {
+      for (const name of names) {
+        if (name.startsWith(namePrefix || '')) {
+          const fqn = `${nsPrefix}/${name}`;
+          items.push({
+            label: `:${fqn}`,
+            kind: CompletionItemKind.Constant,
+            detail: `Keyword in namespace ${nsPrefix}`,
+            textEdit: {
+              range: {
+                start: { line: position.line, character: replaceStart },
+                end: { line: position.line, character: position.character },
+              },
+              newText: `:${fqn}`,
+            },
+            documentation: {
+              kind: MarkupKind.Markdown,
+              value: `**Keyword** \`:${fqn}\`\n\nUsages: ${(keywordIndex.get(fqn) || []).length}`,
+            },
+          });
+        }
+      }
+    }
+  } else {
+    for (const [fqn, locs] of keywordIndex) {
+      if (fqn.startsWith(partial)) {
+        items.push({
+          label: `:${fqn}`,
+          kind: CompletionItemKind.Constant,
+          detail: `${locs.length} usage(s)`,
+          textEdit: {
+            range: {
+              start: { line: position.line, character: replaceStart },
+              end: { line: position.line, character: position.character },
+            },
+            newText: `:${fqn}`,
+          },
+        });
+      }
+    }
+    for (const ns of namespaceIndex.keys()) {
+      if (ns.startsWith(partial)) {
+        items.push({
+          label: `:${ns}/`,
+          kind: CompletionItemKind.Module,
+          detail: `Namespace (${namespaceIndex.get(ns).size} keywords)`,
+          textEdit: {
+            range: {
+              start: { line: position.line, character: replaceStart },
+              end: { line: position.line, character: position.character },
+            },
+            newText: `:${ns}/`,
+          },
+          command: { title: 'Trigger Suggest', command: 'editor.action.triggerSuggest' },
+        });
+      }
+    }
+  }
+
+  return items;
+});
+
+// ─── Hover ────────────────────────────────────────────────────────────
+
+connection.onHover(({ textDocument, position }) => {
+  const doc = documents.get(textDocument.uri);
+  if (!doc) return null;
+
+  const kw = getKeywordAtPosition(doc, position);
+  if (!kw) return null;
+
+  const locs = keywordIndex.get(kw.fqn) || [];
+  const nsInfo = kw.ns
+    ? `**Namespace:** \`${kw.ns}\`\n\n**Name:** \`${kw.name}\``
+    : `**Name:** \`${kw.name}\` *(unqualified)*`;
+
+  return {
+    contents: {
+      kind: MarkupKind.Markdown,
+      value: [
+        `### Keyword \`:${kw.fqn}\``, '',
+        nsInfo, '',
+        `**Usages:** ${locs.length} across ${new Set(locs.map(l => l.uri)).size} file(s)`,
+      ].join('\n'),
+    },
+    range: {
+      start: { line: position.line, character: kw.start },
+      end: { line: position.line, character: kw.end },
+    },
+  };
+});
+
+// ─── Go to Definition ─────────────────────────────────────────────────
+
+connection.onDefinition(({ textDocument, position }) => {
+  const doc = documents.get(textDocument.uri);
+  if (!doc) return null;
+
+  const kw = getKeywordAtPosition(doc, position);
+  if (!kw) return null;
+
+  const locs = keywordIndex.get(kw.fqn);
+  if (!locs || locs.length === 0) return null;
+
+  const first = locs[0];
+  return {
+    uri: first.uri,
+    range: {
+      start: { line: first.line, character: first.character },
+      end: { line: first.line, character: first.endCharacter },
+    },
+  };
+});
+
+// ─── Find References ──────────────────────────────────────────────────
+
+connection.onReferences(({ textDocument, position }) => {
+  const doc = documents.get(textDocument.uri);
+  if (!doc) return [];
+
+  const kw = getKeywordAtPosition(doc, position);
+  if (!kw) return [];
+
+  return (keywordIndex.get(kw.fqn) || []).map(loc => ({
+    uri: loc.uri,
+    range: {
+      start: { line: loc.line, character: loc.character },
+      end: { line: loc.line, character: loc.endCharacter },
+    },
+  }));
+});
+
+// ─── Rename ───────────────────────────────────────────────────────────
+
+connection.onPrepareRename(({ textDocument, position }) => {
+  const doc = documents.get(textDocument.uri);
+  if (!doc) return null;
+
+  const kw = getKeywordAtPosition(doc, position);
+  if (!kw) return null;
+
+  return {
+    range: {
+      start: { line: position.line, character: kw.start },
+      end: { line: position.line, character: kw.end },
+    },
+    placeholder: `:${kw.fqn}`,
+  };
+});
+
+connection.onRenameRequest(({ textDocument, position, newName }) => {
+  const doc = documents.get(textDocument.uri);
+  if (!doc) return null;
+
+  const kw = getKeywordAtPosition(doc, position);
+  if (!kw) return null;
+
+  const newKw = newName.startsWith(':') ? newName : `:${newName}`;
+  const changes = {};
+
+  for (const loc of (keywordIndex.get(kw.fqn) || [])) {
+    if (!changes[loc.uri]) changes[loc.uri] = [];
+    changes[loc.uri].push({
+      range: {
+        start: { line: loc.line, character: loc.character },
+        end: { line: loc.line, character: loc.endCharacter },
+      },
+      newText: newKw,
+    });
+  }
+
+  return { changes };
+});
+
+// ─── Diagnostics ──────────────────────────────────────────────────────
+
+function validateDocument(doc) {
+  const cache = docCache.get(doc.uri);
+  if (!cache) return;
+
+  const { keywords, lineOffsets } = cache;
+  const diagnostics = [];
+
+  for (const { ns, fqn, index, length } of keywords) {
+    if (!ns) continue;
+    const locs = keywordIndex.get(fqn) || [];
+    if (locs.length !== 1) continue;
+
+    const { line, character } = offsetToPosition(lineOffsets, index);
+    diagnostics.push({
+      severity: DiagnosticSeverity.Information,
+      range: {
+        start: { line, character },
+        end: { line, character: character + length },
+      },
+      message: `Keyword :${fqn} is used only once. Possible typo?`,
+      source: 'js-qualified-keywords',
+    });
+  }
+
+  connection.sendDiagnostics({ uri: doc.uri, diagnostics });
+}
+
+// ─── Start ────────────────────────────────────────────────────────────
+
+documents.listen(connection);
+connection.listen();
+connection.console.log('Clojure Keywords LSP server started');

package/lsp-server/start.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Start the clojure-keywords LSP server over stdio.
+exec node "$(dirname "$0")/server.js" --stdio

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "js-qualified-keywords",
+  "version": "0.1.0",
+  "description": "Clojure-style qualified keywords (:ns/name) as a first-class data type in JavaScript, with Babel plugin and LSP support.",
+  "keywords": [
+    "clojure",
+    "keyword",
+    "babel-plugin",
+    "lsp",
+    "data-types"
+  ],
+  "homepage": "https://github.com/YOUR_ORG/clojure-keywords-js#readme",
+  "bugs": {
+    "url": "https://github.com/YOUR_ORG/clojure-keywords-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YOUR_ORG/clojure-keywords-js.git"
+  },
+  "license": "MIT",
+  "main": "runtime/index.js",
+  "exports": {
+    ".": "./runtime/index.js",
+    "./runtime": "./runtime/index.js",
+    "./babel-plugin": "./babel-plugin/index.js"
+  },
+  "files": [
+    "runtime/",
+    "babel-plugin/",
+    "lib/",
+    "lsp-server/server.js",
+    "lsp-server/start.sh",
+    "lsp-server/package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node tests/scan.test.js && node tests/babel-plugin.test.js && node tests/runtime.test.js"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0"
+  },
+  "peerDependencies": {
+    "@babel/core": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@babel/core": {
+      "optional": true
+    }
+  }
+}

package/runtime/index.js

@@ -0,0 +1,4 @@
+const { Keyword, kw } = require('./keyword');
+const { KeywordMap } = require('./keyword-map');
+
+module.exports = { Keyword, kw, KeywordMap };

package/runtime/keyword-map.js

@@ -0,0 +1,69 @@
+/**
+ * KeywordMap — a Map that accepts Keyword instances as keys with value equality.
+ *
+ * Regular JS Maps use reference equality for object keys, so two Keyword
+ * instances with the same ns/name would be treated as different keys.
+ * Because Keywords are interned, reference equality IS value equality —
+ * but KeywordMap also accepts plain strings like ":user/name" as keys.
+ */
+
+const { Keyword } = require('./keyword');
+
+class KeywordMap {
+  #map = new Map();
+
+  #resolve(key) {
+    if (key instanceof Keyword) return key;
+    if (typeof key === 'string') return Keyword.of(key);
+    throw new TypeError(`KeywordMap key must be a Keyword or string, got ${typeof key}`);
+  }
+
+  set(key, value) {
+    this.#map.set(this.#resolve(key), value);
+    return this;
+  }
+
+  get(key) {
+    return this.#map.get(this.#resolve(key));
+  }
+
+  has(key) {
+    return this.#map.has(this.#resolve(key));
+  }
+
+  delete(key) {
+    return this.#map.delete(this.#resolve(key));
+  }
+
+  get size() { return this.#map.size; }
+
+  entries() { return this.#map.entries(); }
+  keys() { return this.#map.keys(); }
+  values() { return this.#map.values(); }
+  [Symbol.iterator]() { return this.#map[Symbol.iterator](); }
+
+  forEach(cb, thisArg) {
+    this.#map.forEach((v, k) => cb.call(thisArg, v, k, this));
+  }
+
+  toObject() {
+    const obj = {};
+    for (const [k, v] of this.#map) obj[k.toString()] = v;
+    return obj;
+  }
+
+  toJSON() { return this.toObject(); }
+
+  /**
+   * Build a KeywordMap from a plain object whose keys are keyword strings.
+   * @param {Record<string, any>} obj
+   * @returns {KeywordMap}
+   */
+  static fromObject(obj) {
+    const m = new KeywordMap();
+    for (const [k, v] of Object.entries(obj)) m.set(k, v);
+    return m;
+  }
+}
+
+module.exports = { KeywordMap };

package/runtime/keyword.js

@@ -0,0 +1,89 @@
+/**
+ * Clojure-style Keyword for JavaScript.
+ * Supports both simple (:name) and qualified (:ns/name) keywords.
+ * Keywords are interned — same ns/name always returns the same instance.
+ */
+
+const _intern = new Map();
+
+class Keyword {
+  #ns;
+  #name;
+
+  constructor(ns, name) {
+    if (name === undefined) {
+      const parsed = Keyword.parse(ns);
+      this.#ns = parsed.ns;
+      this.#name = parsed.name;
+    } else {
+      this.#ns = ns;
+      this.#name = name;
+    }
+    Object.freeze(this);
+  }
+
+  get ns() { return this.#ns; }
+  get name() { return this.#name; }
+  get fqn() { return this.#ns ? `${this.#ns}/${this.#name}` : this.#name; }
+
+  toString() { return `:${this.fqn}`; }
+  toJSON() { return this.toString(); }
+
+  equals(other) {
+    return other instanceof Keyword && other.ns === this.#ns && other.name === this.#name;
+  }
+
+  valueOf() { return this.toString(); }
+
+  /**
+   * Intern a keyword — same ns/name always returns the same instance.
+   * @param {string|null} ns  - namespace, or a full ":ns/name" string if name omitted
+   * @param {string} [name]
+   * @returns {Keyword}
+   */
+  static of(ns, name) {
+    if (name === undefined) {
+      const parsed = Keyword.parse(ns);
+      ns = parsed.ns;
+      name = parsed.name;
+    }
+    const key = ns ? `${ns}/${name}` : name;
+    if (_intern.has(key)) return _intern.get(key);
+    const k = new Keyword(ns, name);
+    _intern.set(key, k);
+    return k;
+  }
+
+  /**
+   * Parse a keyword string like ":ns/name", "ns/name", or ":name".
+   * @param {string} s
+   * @returns {{ ns: string|null, name: string }}
+   */
+  static parse(s) {
+    if (typeof s !== 'string') throw new TypeError(`Expected string, got ${typeof s}`);
+    const str = s.startsWith(':') ? s.slice(1) : s;
+    if (!str) throw new Error('Keyword name cannot be empty');
+    const slashIdx = str.indexOf('/');
+    if (slashIdx === -1) return { ns: null, name: str };
+    const ns = str.slice(0, slashIdx);
+    const name = str.slice(slashIdx + 1);
+    if (!ns) throw new Error('Keyword namespace cannot be empty');
+    if (!name) throw new Error('Keyword name cannot be empty');
+    return { ns, name };
+  }
+
+  /** Clear the intern cache. Mainly useful for testing. */
+  static clearCache() { _intern.clear(); }
+}
+
+/**
+ * Shorthand factory. Used by the Babel plugin output.
+ * @param {string|null} ns
+ * @param {string} name
+ * @returns {Keyword}
+ */
+function kw(ns, name) {
+  return Keyword.of(ns, name);
+}
+
+module.exports = { Keyword, kw };