nvim-keymap-migrator 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# nvim-keymap-migrator
+
+A CLI tool that extracts user-defined keymaps from your Neovim configuration and integrates them with vim emulator plugins (IdeaVim, VSCodeVim, etc.).
+
+## Warning
+
+**Back up your files before running this tool!**. This tool was made for me, so it may have unintended consequences on your setup. Always review the changes it proposes before applying them.
+
+This tool modifies the following files:
+
+- `~/.ideavimrc` (IntelliJ/IdeaVim config)
+- VS Code `settings.json` (location varies by platform - see below)
+
+While `--clean` attempts to cleanly remove all changes, **always back up these files** before running:
+
+| Platform | VS Code settings.json                                   |
+| -------- | ------------------------------------------------------- |
+| Linux    | `~/.config/Code/User/settings.json`                     |
+| macOS    | `~/Library/Application Support/Code/User/settings.json` |
+| Windows  | `%APPDATA%/Code/User/settings.json`                     |
+
+## Why?
+
+When moving from Neovim to another editor (VS Code, IntelliJ, etc.), you'll likely use a vim emulator plugin like IdeaVim or VSCodeVim. This tool extracts your custom keymaps from your Neovim config so you don't have to manually recreate them.
+
+## Installation
+
+```bash
+npm install -g nvim-keymap-migrator
+```
+
+## Requirements
+
+- Node.js 18+
+- Neovim 0.8+ (for `vim.keymap.set` and `vim.api.nvim_get_keymap`)
+- Editor with a Vim emulator plugin (e.g., IdeaVim for IntelliJ, VSCodeVim for VS Code)
+- Your Neovim config must be loadable via `nvim --headless`
+
+## Usage
+
+```bash
+nvim-keymap-migrator <editor> [options]
+```
+
+### Editors
+
+- `vscode` - Generate and integrate keybindings for VS Code
+- `intellij` - Generate and integrate keybindings for IntelliJ
+
+### Options
+
+- `--dry-run` - Print report without writing files
+- `--clean` - Remove managed keybindings from editor config
+- `--help, -h` - Show help
+- `--version, -v` - Show version
+
+### Examples
+
+```bash
+# Integrate with VS Code
+nvim-keymap-migrator vscode
+
+# Integrate with IntelliJ
+nvim-keymap-migrator intellij
+
+# Preview without making changes
+nvim-keymap-migrator vscode --dry-run
+
+# Remove VS Code keybindings
+nvim-keymap-migrator vscode --clean
+
+# Remove IntelliJ mappings
+nvim-keymap-migrator intellij --clean
+```
+
+## How It Works
+
+The tool extracts keymaps from your Neovim config and categorizes them:
+
+1. **IDE actions** - Keymaps that can be translated to IDE-specific actions (e.g., LSP, file explorer)
+2. **Pure Vim mappings** - Native Vim keymaps that work in any Vim emulator
+3. **Plugin mappings** - Keymaps from plugins (require manual configuration)
+4. **Unsupported** - Keymaps that couldn't be categorized
+
+### IntelliJ
+
+Mappings are appended to `~/.ideavimrc` wrapped in markers:
+
+```vim
+" <<< nvim-keymap-migrator start >>>
+" Managed by nvim-keymap-migrator. Run with --clean to remove.
+
+" Pure Vim mappings (native Vim motions)
+nnoremap K mzK`z
+vnoremap K :m '<-2<CR>gv=gv
+
+" IDE action mappings
+nnoremap <leader>ff <Action>(GotoFile)
+" >>> nvim-keymap-migrator end <<<
+```
+
+Re-running replaces the content between markers. Use `--clean` to remove.
+
+### VS Code
+
+VS Code uses a two-pronged approach:
+
+1. **IDE actions** - Merged directly into `settings.json`:
+
+```json
+"vim.normalModeKeyBindings": [
+  { "before": ["<leader>", "f"], "commands": ["workbench.action.quickOpen"], "_managedBy": "nvim-keymap-migrator" }
+]
+```
+
+2. **Pure Vim mappings** - Written to a shared `.vimrc` file, configured via `vim.vimrc.path` and `vim.vimrc.enable`:
+
+```json
+"vim.vimrc.path": "~/.config/nvim-keymap-migrator/.vimrc",
+"vim.vimrc.enable": true
+```
+
+The tool manages both settings:
+
+- `vim.vimrc.path` - Set to point to the shared .vimrc
+- `vim.vimrc.enable` - Set to `true` only if unset (respects existing user values)
+
+Re-running replaces managed keybindings. Use `--clean` to remove them.
+
+## Namespace
+
+A small namespace directory stores shared files:
+
+```
+~/.config/nvim-keymap-migrator/
+  .vimrc           Shared pure-Vim mappings (read by VS Code and IntelliJ)
+  metadata.json    Extraction metadata
+```
+
+## Supported Intents
+
+The tool detects and translates these keymap intents:
+
+### Navigation
+
+- `navigation.file_explorer` - File explorer (`:Ex`, `<leader>pv`)
+- `navigation.find_files` - Quick open files
+- `navigation.live_grep` - Search in files
+- `navigation.buffers` - Switch buffers
+- `navigation.recent_files` - Recent files
+- `navigation.grep_string` - Search word under cursor
+
+### LSP
+
+- `lsp.definition` - Go to definition (`gd`)
+- `lsp.declaration` - Go to declaration (`gD`)
+- `lsp.references` - Find references (`gr`)
+- `lsp.implementation` - Go to implementation (`gi`)
+- `lsp.hover` - Show hover info
+- `lsp.signature_help` - Signature help
+- `lsp.rename` - Rename symbol
+- `lsp.code_action` - Code actions
+- `lsp.format` - Format document
+
+### Git
+
+- `git.fugitive` - Git commands
+- `git.push` / `git.pull` - Push/pull
+- `git.commit` - Git commit
+
+### Pure Vim Mappings
+
+Native Vim motions and commands are detected and output as pure Vim mappings, so any mapping from one Vim command to another is included here.
+
+These work out of the box in any Vim emulator.
+
+## What Gets Extracted
+
+Only **user-defined** keymaps are extracted (not plugin defaults or built-in mappings). The tool identifies these by checking:
+
+- If the keymap's callback source is in your config directory
+- If the keymap has a `desc` field
+- If the keymap's script path starts with your config path
+
+## Limitations
+
+- `<Lua function>` keymaps without a command string are included as comments (vim emulators can't execute arbitrary Lua)
+- Buffer-local keymaps are marked with `<buffer>` - they'll only work in the current buffer
+- Some plugin-specific keymaps may require manual configuration
+
+## License
+
+GPL-3.0-only

package/index.js

@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { extractKeymaps } from "./src/extractor.js";
+import { detectConfig } from "./src/config.js";
+import { detectIntents } from "./src/detector.js";
+import { loadMappings, lookupIntent } from "./src/registry.js";
+import { generateVimrc, isPureVimMapping } from "./src/generators/vimrc.js";
+import { generateIdeaVimrc } from "./src/generators/intellij.js";
+import { generateVSCodeBindings } from "./src/generators/vscode.js";
+import { generateReport } from "./src/report.js";
+import { ensureNamespaceDir, getRcPath } from "./src/namespace.js";
+import {
+  integrateIdeaVim,
+  cleanIdeaVim,
+  integrateVSCode,
+  cleanVSCode,
+  saveMetadata,
+} from "./src/install.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
+const args = process.argv.slice(2);
+
+await main(args);
+
+function checkNeovimAvailable() {
+  return new Promise((resolve) => {
+    const proc = spawn("nvim", ["--version"], { stdio: "ignore" });
+    proc.on("error", () => resolve(false));
+    proc.on("close", (code) => resolve(code === 0));
+  });
+}
+
+async function main(argv) {
+  const parsed = parseArgs(argv);
+
+  if (parsed.error) {
+    printHelp(parsed.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (parsed.version) {
+    console.log(pkg.version);
+    return;
+  }
+
+  if (!parsed.editor) {
+    printHelp('Missing required <editor>. Use "vscode" or "intellij".');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!["vscode", "intellij"].includes(parsed.editor)) {
+    printHelp(`Unsupported editor: ${parsed.editor}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.clean) {
+    await handleClean(parsed.editor);
+    return;
+  }
+
+  await handleGenerate(parsed);
+}
+
+async function handleGenerate(parsed) {
+  try {
+    const nvimAvailable = await checkNeovimAvailable();
+    if (!nvimAvailable) {
+      console.error("Error: Neovim not found. Please install Neovim 0.8+");
+      process.exitCode = 1;
+      return;
+    }
+
+    const config = await detectConfig();
+    const extracted = await extractKeymaps();
+    const intents = detectIntents(extracted);
+    const registry = loadMappings();
+
+    if (intents.length === 0) {
+      console.log(`No user-defined keymaps found in your Neovim config.
+Nothing to write.`);
+      return;
+    }
+
+    const translated = [];
+    const manual = [];
+    const unsupported = [];
+
+    for (const item of intents) {
+      if (!item.intent) {
+        unsupported.push(item);
+        continue;
+      }
+
+      const command = lookupIntent(item.intent, parsed.editor, registry);
+      if (!command) {
+        manual.push(item);
+        continue;
+      }
+
+      translated.push({ ...item, command });
+    }
+
+    const vimrcText = generateVimrc(intents);
+    const pureVim = intents.filter(isPureVimMapping);
+    const counts = {
+      total: intents.length,
+      translated: translated.length,
+      pureVim: pureVim.length,
+      manual: manual.length,
+      unsupported: unsupported.length,
+    };
+
+    const leaderLabel = formatKeyDisplay(config.leader);
+
+    if (parsed.dryRun) {
+      const report = generateReport({
+        target: parsed.editor,
+        configPath: config.config_path,
+        leader: leaderLabel,
+        total: intents.length,
+        translated,
+        manual,
+        manualPlugin: manual.filter((item) => item.category === "plugin"),
+        manualOther: manual.filter((item) => item.category !== "plugin"),
+        pureVim,
+        unsupported: unsupported.filter((item) => !isPureVimMapping(item)),
+        outputs: [],
+      });
+      console.log(report.trimEnd());
+      printDetectionWarnings(config, extracted);
+      return;
+    }
+
+    await ensureNamespaceDir();
+    const vimrcPath = getRcPath("neovim");
+    await writeFile(vimrcPath, vimrcText, "utf8");
+
+    console.log(`=== nvim-keymap-migrator ===
+Editor: ${parsed.editor}
+Config: ${config.config_path}
+Leader: ${leaderLabel}
+
+`);
+
+    if (parsed.editor === "intellij") {
+      const ideaVimrcResult = generateIdeaVimrc(intents, { registry });
+      const ideaVimrcText = ideaVimrcResult.text;
+      const ideaDefaults = ideaVimrcResult.defaultsAdded ?? 0;
+      const result = await integrateIdeaVim(ideaVimrcText, {
+        leader: config.leader,
+      });
+
+      await saveMetadata(config, counts);
+
+      console.log(`Shared .vimrc: ${vimrcPath}
+
+IntelliJ:
+  Mappings appended to ~/.ideavimrc${result.updated ? "\n  (replaced previous mappings)" : ""}
+  Defaults added: ${ideaDefaults}`);
+    } else if (parsed.editor === "vscode") {
+      const vscodeBindings = generateVSCodeBindings(intents, { registry });
+      const result = await integrateVSCode(vscodeBindings, {
+        leader: config.leader,
+      });
+
+      await saveMetadata(config, counts, {
+        leaderSet: result.setLeader,
+        vimrcPathSet: result.setVimrcPath,
+        vimrcEnableSet: result.setVimrcEnable,
+      });
+
+      let vscodeOutput = `Shared .vimrc: ${vimrcPath}
+
+VS Code:
+  Keybindings merged into settings.json`;
+
+      if (result.setVimrcPath) {
+        vscodeOutput +=
+          "\n  vim.vimrc.path set in settings.json (reads shared .vimrc)";
+      }
+      if (result.setVimrcEnable) {
+        vscodeOutput +=
+          "\n  vim.vimrc.enable set in settings.json (loads shared .vimrc)";
+      }
+      if (result.setLeader) {
+        vscodeOutput += "\n  vim.leader set in settings.json";
+      }
+      if (result.sections) {
+        vscodeOutput += `\n  Sections: ${result.sections.join(", ")}`;
+      }
+      if (result.warnings) {
+        for (const w of result.warnings) {
+          vscodeOutput += `\n  ${w}`;
+        }
+      }
+      const vsDefaults = vscodeBindings._meta?.defaultsAdded ?? 0;
+      vscodeOutput += `\n  Defaults added: ${vsDefaults}`;
+
+      console.log(vscodeOutput);
+    }
+
+    console.log(`
+Total keymaps: ${counts.total}
+Translated: ${counts.translated}
+Pure Vim: ${counts.pureVim}
+Manual review: ${counts.manual}
+Unsupported: ${counts.unsupported}`);
+
+    printDetectionWarnings(config, extracted);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+async function handleClean(editor) {
+  try {
+    console.log(`=== nvim-keymap-migrator --clean ===
+Editor: ${editor}
+
+`);
+
+    if (editor === "intellij") {
+      const result = await cleanIdeaVim();
+      if (result.cleaned) {
+        console.log("Removed managed mappings from ~/.ideavimrc");
+      } else {
+        console.log("No managed mappings found in ~/.ideavimrc");
+      }
+    } else if (editor === "vscode") {
+      const result = await cleanVSCode();
+      if (result.cleaned) {
+        let output = `Removed ${result.removed} keybinding(s) from settings.json`;
+        if (result.sections) {
+          output += `\nSections cleaned: ${result.sections.join(", ")}`;
+        }
+        if (result.removedVimrcPath) {
+          output += "\nRemoved vim.vimrc.path from settings.json";
+        }
+        if (result.removedVimrcEnable) {
+          output += "\nRemoved vim.vimrc.enable from settings.json";
+        }
+        if (result.removedLeader) {
+          output += "\nRemoved vim.leader from settings.json";
+        }
+        console.log(output);
+      } else {
+        console.log("No managed keybindings found in settings.json");
+      }
+    }
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+function parseArgs(argv) {
+  const flags = {
+    help: false,
+    version: false,
+    dryRun: false,
+    clean: false,
+    editor: null,
+    error: null,
+  };
+
+  const tokens = [...argv];
+
+  for (let i = 0; i < tokens.length; i += 1) {
+    const arg = tokens[i];
+
+    if (arg === "--help" || arg === "-h" || arg === "help") {
+      flags.help = true;
+      continue;
+    }
+
+    if (arg === "--version" || arg === "-v" || arg === "version") {
+      flags.version = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      flags.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--clean") {
+      flags.clean = true;
+      continue;
+    }
+
+    if (arg === "run") {
+      continue;
+    }
+
+    if (!flags.editor && ["vscode", "intellij"].includes(arg)) {
+      flags.editor = arg;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      flags.error = `Unknown option: ${arg}`;
+      return flags;
+    }
+
+    flags.error = `Unknown argument: ${arg}`;
+    return flags;
+  }
+
+  return flags;
+}
+
+function printHelp(error) {
+  if (error) {
+    console.error(error + "\n");
+  }
+
+  const help = `Usage: ${pkg.bin["nvim-keymap-migrator"]} <editor> [options]
+
+Editors:
+  vscode             Generate and integrate keybindings for VS Code
+  intellij           Generate and integrate keybindings for IntelliJ
+
+Options:
+  --dry-run          Print report without writing files
+  --clean            Remove managed keybindings from editor config
+  --help, -h         Show help
+  --version, -v      Show version
+
+Examples:
+  nvim-keymap-migrator vscode        # Integrate with VS Code
+  nvim-keymap-migrator intellij      # Integrate with IntelliJ
+  nvim-keymap-migrator vscode --dry-run  # Preview without changes
+  nvim-keymap-migrator vscode --clean    # Remove VS Code keybindings
+
+Files modified:
+  IntelliJ: ~/.ideavimrc
+  VS Code:  settings.json (platform-specific path)`;
+
+  console.log(help);
+}
+
+function formatKeyDisplay(value) {
+  if (value == null) {
+    return "<none>";
+  }
+
+  if (value.length === 0) {
+    return "<empty>";
+  }
+
+  const special = {
+    " ": "<space>",
+    "\t": "<Tab>",
+    "\n": "<NL>",
+    "\r": "<CR>",
+    "\u001B": "<Esc>",
+  };
+
+  return [...value]
+    .map((char) => special[char] ?? printableChar(char))
+    .join("");
+}
+
+function printableChar(char) {
+  const code = char.charCodeAt(0);
+  if (code < 32) {
+    return `<0x${code.toString(16).padStart(2, "0")}>`;
+  }
+  if (char === "\\") {
+    return "\\\\";
+  }
+  return char;
+}
+
+function printDetectionWarnings(config, extracted) {
+  const extractionMeta = extracted?._meta ?? {};
+  const extractionWarnings = Array.isArray(extracted?._warnings)
+    ? extracted._warnings
+    : [];
+
+  if (config.fallback_from) {
+    console.warn(
+      `Warning: config detection fell back from ${config.fallback_from} to ${config.mode} (${config.fallback_reason})`,
+    );
+  }
+
+  if (Array.isArray(config.warnings) && config.warnings.length > 0) {
+    console.warn(`Config warnings (${config.warnings.length}):`);
+    for (const warning of config.warnings.slice(0, 5)) {
+      console.warn(`- ${warning}`);
+    }
+  }
+
+  if (extractionMeta.fallback_from) {
+    console.warn(
+      `Warning: extraction fell back from ${extractionMeta.fallback_from} to ${extractionMeta.extraction_mode} (${extractionMeta.fallback_reason})`,
+    );
+  }
+
+  if (extractionWarnings.length > 0) {
+    console.warn(`Extraction warnings (${extractionWarnings.length}):`);
+    for (const warning of extractionWarnings.slice(0, 5)) {
+      console.warn(`- ${warning}`);
+    }
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "nvim-keymap-migrator",
+  "version": "1.0.0",
+  "description": "Creates a keymap file from your Neovim config to migrate your keybinds to other editors.",
+  "files": [
+    "index.js",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "nvim-keymap-migrator": "index.js"
+  },
+  "keywords": [
+    "tools",
+    "neovim",
+    "nvim",
+    "editor",
+    "ide"
+  ],
+  "homepage": "https://github.com/DerekCorniello/nvim-keymap-migrator#readme",
+  "bugs": {
+    "url": "https://github.com/DerekCorniello/nvim-keymap-migrator/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DerekCorniello/nvim-keymap-migrator.git"
+  },
+  "license": "GPL-3.0-only",
+  "author": "Derek Corniello",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "lint": "prettier --check ."
+  },
+  "devDependencies": {
+    "prettier": "^3.0.0"
+  }
+}