apotheke 0.0.1

package/README.md

@@ -0,0 +1,248 @@
+# apotheke
+
+Import organizer for JavaScript and TypeScript projects. Groups, sorts, and deduplicates imports based on a simple config file.
+
+```ts
+// Before
+import { useQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import { createRoute } from '@tanstack/react-router';
+import { tsr } from '../api/tsr';
+import useLoggedUser from '../hooks/use-logged-user';
+
+// After
+// React
+import { useMemo } from 'react';
+
+// Hooks
+import useLoggedUser from '../hooks/use-logged-user';
+
+// Api
+import { tsr } from '../api/tsr';
+import { useQuery } from '@tanstack/react-query';
+
+// Navigation
+import { createRoute } from '@tanstack/react-router';
+```
+
+## Requirements
+
+- Node.js ≥ 18
+
+## Installation
+
+```sh
+npm install -D apotheke
+# or
+pnpm add -D apotheke
+```
+
+## Usage
+
+```sh
+apotheke --write src/**/*.{ts,tsx}     # format in place
+apotheke --check src/**/*.{ts,tsx}     # CI — exit 1 if anything would change
+apotheke --diff  src/**/*.{ts,tsx}     # print diff without writing
+apotheke --stdin-filepath src/app.tsx  # read from stdin, write to stdout
+```
+
+## Config
+
+Create `apotheke.config.mjs` at your project root:
+
+```js
+// apotheke.config.mjs
+export default {
+    groups: [
+        { name: 'React', match: ['react', 'react-dom', 'react-*'] },
+        { name: 'Hooks', match: ['**/hooks/**'] },
+        { name: 'Api', match: ['**/api/**', '@tanstack/react-query'] },
+        { name: 'Navigation', match: ['@tanstack/react-router'] },
+        { name: 'Assets', match: ['lucide-react'] }
+    ],
+    aliases: {
+        '@': './src' // mirrors tsconfig paths — auto-read if omitted
+    },
+    groupSeparator: true, // blank line between groups
+    groupComments: true   // // GroupName header above each group
+};
+```
+
+Apotheke also reads `tsconfig.json` (or `jsconfig.json`) automatically to pick up `paths` aliases and `baseUrl`, so you often don't need to set `aliases` manually.
+
+Unmatched imports collect in an **Others** group at the end. Side-effect imports (`import './styles.css'`) always go first.
+
+### Monorepo
+
+Place a root config and extend it per-package:
+
+```js
+// apps/web/apotheke.config.mjs
+export default {
+    extends: '../../apotheke.config.mjs',
+    groups: [{ name: 'Shared', match: ['@acme/*'] }]
+};
+```
+
+---
+
+## Prettier plugin
+
+Apotheke ships as a prettier plugin. When loaded, it runs as a `preprocess` step — apotheke organises imports first, then prettier formats the result. One pass, correct order, no conflicts.
+
+**Requirements:** Prettier v3 or later (v3 supports async `preprocess`; v2 does not).
+
+### Permanent setup
+
+**1. Install apotheke**
+
+```sh
+pnpm add -D apotheke
+```
+
+**2. Add the plugin to your prettier config**
+
+```js
+// .prettierrc.js
+module.exports = {
+    plugins: ['apotheke'],
+};
+```
+
+That's it — `prettier --write` will now organise imports automatically.
+
+### Quick test (without installing)
+
+```sh
+cd /path/to/your-project
+npx prettier@3 \
+  --plugin /path/to/apotheke/dist/index.js \
+  --write 'src/App.tsx'
+```
+
+### VS Code on-save
+
+Install the [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extension. Because `prettier.format()` calls our plugin's `preprocess` hook directly, no extra config is needed:
+
+```json
+{
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "editor.formatOnSave": true
+}
+```
+
+### Pre-commit with Husky + lint-staged
+
+```json
+{
+    "lint-staged": {
+        "*.{ts,tsx,js,jsx}": ["prettier --write"]
+    }
+}
+```
+
+### Prettier v2 fallback
+
+If you can't upgrade to prettier v3, use the CLI sequentially via lint-staged:
+
+```json
+{
+    "lint-staged": {
+        "*.{ts,tsx,js,jsx}": [
+            "apotheke --write",
+            "prettier --write"
+        ]
+    }
+}
+```
+
+---
+
+## Testing locally without publishing
+
+### Option 1 — Direct invocation (no setup)
+
+```sh
+node /path/to/apotheke/dist/cli.js --write 'src/**/*.{ts,tsx}'
+```
+
+Build first if needed: `cd /path/to/apotheke && pnpm build`
+
+### Option 2 — `pnpm link` (recommended)
+
+**In the apotheke repo:**
+
+```sh
+pnpm build
+pnpm link --global
+```
+
+**In your target repo:**
+
+```sh
+pnpm link --global apotheke
+```
+
+Now `apotheke --write src/**/*.tsx` works as if it were installed normally. You'll need to re-run `pnpm build` in the apotheke repo after making source changes.
+
+**To unlink when done:**
+
+```sh
+# In your target repo
+pnpm unlink --global apotheke
+
+# In the apotheke repo
+pnpm unlink --global
+```
+
+### Option 3 — Path dependency in `package.json`
+
+```sh
+pnpm add /path/to/apotheke
+```
+
+---
+
+## Development
+
+```sh
+pnpm install
+
+# Build (required before running locally or testing the plugin)
+pnpm build
+
+# Run all tests (unit + e2e)
+pnpm test
+
+# Unit tests only
+pnpm test:unit
+
+# E2E tests against real repos (cloned automatically on first run)
+pnpm test:e2e
+
+# Type check
+pnpm typecheck
+```
+
+### Project structure
+
+```
+src/
+  parser.ts        OXC-based import extractor
+  grouper.ts       Glob-based group assignment
+  sorter.ts        Alphabetical sort, type imports float to top
+  deduplicator.ts  Merge named/default imports from same specifier
+  printer.ts       Reconstruct import block with group headers
+  config.ts        Load apotheke.config.mjs, merge tsconfig aliases
+  format.ts        Top-level formatImports(source, config)
+  types.ts         Shared types
+cli.ts             CLI source (Node.js)
+index.ts           Prettier plugin + programmatic API
+dist/
+  cli.js           Compiled CLI — run with node or via the apotheke bin
+  index.js         Compiled prettier plugin
+  index.d.ts       Types for programmatic use
+tests/
+  unit/            76 unit tests
+  e2e/             20 e2e tests against sonner and tremor
+```

package/dist/cli.js

@@ -0,0 +1,532 @@
+#!/usr/bin/env node
+
+// cli.ts
+import path3 from "path";
+import fs from "fs";
+import { execFileSync } from "child_process";
+import fg from "fast-glob";
+
+// src/config.ts
+import path from "path";
+import { existsSync, readFileSync } from "fs";
+function mergeConfigs(parent, child) {
+  const mergedGroups = [...parent.groups];
+  for (const childGroup of child.groups ?? []) {
+    const existingIdx = mergedGroups.findIndex((g) => g.name === childGroup.name);
+    if (existingIdx >= 0) {
+      mergedGroups[existingIdx] = childGroup;
+    } else {
+      mergedGroups.push(childGroup);
+    }
+  }
+  return {
+    ...parent,
+    ...child,
+    groups: mergedGroups,
+    aliases: { ...parent.aliases ?? {}, ...child.aliases ?? {} }
+  };
+}
+async function loadConfig(configPath) {
+  const mod = await import(configPath);
+  const userConfig = mod.default ?? mod;
+  const configDir = path.dirname(configPath);
+  const config = { ...userConfig };
+  const tsconfig = loadTsConfig(configDir);
+  if (tsconfig) {
+    const opts = tsconfig.compilerOptions ?? {};
+    if (opts.baseUrl && !config.baseUrl) {
+      config.baseUrl = opts.baseUrl;
+    }
+    if (opts.paths) {
+      const aliases = { ...config.aliases ?? {} };
+      for (const [aliasPattern, targets] of Object.entries(
+        opts.paths
+      )) {
+        const alias = aliasPattern.replace(/\/\*$/, "");
+        const target = (targets[0] ?? "").replace(/\/\*$/, "");
+        if (!aliases[alias]) aliases[alias] = target;
+      }
+      config.aliases = aliases;
+    }
+  }
+  if (userConfig.extends) {
+    const parentPath = path.resolve(configDir, userConfig.extends);
+    if (!existsSync(parentPath)) {
+      throw new Error(
+        `apotheke: extended config not found: ${parentPath}
+  (referenced from ${configPath} via "extends": "${userConfig.extends}")`
+      );
+    }
+    const parent = await loadConfig(parentPath);
+    return mergeConfigs(parent, config);
+  }
+  return config;
+}
+function loadTsConfig(dir) {
+  const tsconfigPath = path.join(dir, "tsconfig.json");
+  if (!existsSync(tsconfigPath)) return null;
+  try {
+    const text = readFileSync(tsconfigPath, "utf8");
+    const cleaned = text.replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    return JSON.parse(cleaned);
+  } catch {
+    return null;
+  }
+}
+
+// src/parser.ts
+import { parseSync } from "oxc-parser";
+function parseImports(source) {
+  const result = parseSync("file.tsx", source);
+  const comments = result.comments;
+  const nodes = [];
+  for (const node of result.program.body) {
+    if (node.type !== "ImportDeclaration") continue;
+    const specifier = node.source.value;
+    let defaultImport;
+    const namedImports = [];
+    let namespaceImport;
+    for (const s of node.specifiers) {
+      if (s.type === "ImportDefaultSpecifier") {
+        defaultImport = s.local.name;
+      } else if (s.type === "ImportNamespaceSpecifier") {
+        namespaceImport = s.local.name;
+      } else if (s.type === "ImportSpecifier") {
+        const imported = s.imported;
+        const name = imported.type === "Identifier" ? imported.name : imported.value;
+        const localName = s.local.name;
+        const kind = s.importKind === "type" ? "type" : "value";
+        const named = { name, kind };
+        if (localName !== name) named.alias = localName;
+        namedImports.push(named);
+      }
+    }
+    const importKind = node.importKind === "type" ? "type" : "value";
+    const isSideEffect = node.specifiers.length === 0 && importKind === "value";
+    const importNode = {
+      specifier,
+      namedImports,
+      isSideEffect,
+      importKind,
+      start: node.start,
+      end: node.end
+    };
+    if (defaultImport) importNode.defaultImport = defaultImport;
+    if (namespaceImport) importNode.namespaceImport = namespaceImport;
+    const attached = findAttachedComment(source, node.start, comments);
+    if (attached) importNode.attachedComment = attached;
+    nodes.push(importNode);
+  }
+  return nodes;
+}
+function findAttachedComment(source, importStart, comments) {
+  const linesBefore = source.slice(0, importStart).split("\n");
+  const importLine = linesBefore.length - 1;
+  for (const comment of comments) {
+    if (comment.type !== "Line") continue;
+    const commentLines = source.slice(0, comment.end).split("\n");
+    const commentLine = commentLines.length - 1;
+    if (commentLine === importLine - 1) {
+      return `//${comment.value}`;
+    }
+  }
+  return void 0;
+}
+
+// src/deduplicator.ts
+function deduplicateImports(imports) {
+  const map = /* @__PURE__ */ new Map();
+  for (const node of imports) {
+    const key = `${node.importKind}::${node.specifier}`;
+    if (!map.has(key)) {
+      map.set(key, { ...node, namedImports: [...node.namedImports] });
+      continue;
+    }
+    const existing = map.get(key);
+    if (node.defaultImport && !existing.defaultImport) {
+      existing.defaultImport = node.defaultImport;
+    }
+    if (node.namespaceImport && !existing.namespaceImport) {
+      existing.namespaceImport = node.namespaceImport;
+    }
+    for (const named of node.namedImports) {
+      if (!existing.namedImports.some((n) => n.name === named.name && n.kind === named.kind)) {
+        existing.namedImports.push(named);
+      }
+    }
+    existing.isSideEffect = !existing.defaultImport && !existing.namespaceImport && existing.namedImports.length === 0;
+  }
+  return Array.from(map.values());
+}
+
+// src/grouper.ts
+import path2 from "path";
+function groupImports(imports, config, options = {}) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const node of imports) {
+    const groupName = assignGroup(node, config, options);
+    if (!buckets.has(groupName)) buckets.set(groupName, []);
+    buckets.get(groupName).push(node);
+  }
+  const result = [];
+  if (buckets.has("SideEffects")) {
+    result.push({ name: "SideEffects", imports: buckets.get("SideEffects") });
+  }
+  for (const group of config.groups) {
+    if (buckets.has(group.name)) {
+      result.push({ name: group.name, imports: buckets.get(group.name) });
+    }
+  }
+  if (buckets.has("Others")) {
+    result.push({ name: "Others", imports: buckets.get("Others") });
+  }
+  return result;
+}
+function assignGroup(node, config, options) {
+  if (node.isSideEffect) return "SideEffects";
+  const canonicalPath = resolveCanonicalPath(node.specifier, config, options);
+  for (const group of config.groups) {
+    for (const pattern of group.match) {
+      if (matches(node.specifier, pattern)) return group.name;
+      if (canonicalPath && matches(canonicalPath, pattern)) return group.name;
+    }
+  }
+  return "Others";
+}
+function resolveCanonicalPath(specifier, config, options) {
+  if (specifier.startsWith(".") || specifier.startsWith("/")) {
+    const base = options.fileDir ?? process.cwd();
+    return path2.resolve(base, specifier);
+  }
+  const aliases = config.aliases ?? {};
+  for (const [alias, target] of Object.entries(aliases)) {
+    const prefix = alias.endsWith("/") ? alias : `${alias}/`;
+    if (specifier === alias || specifier.startsWith(prefix)) {
+      const rest = specifier.slice(prefix.length);
+      const root = options.rootDir ?? process.cwd();
+      const resolved = path2.resolve(root, target, rest);
+      return resolved;
+    }
+  }
+  return null;
+}
+function matches(value, pattern) {
+  return globToRegex(pattern).test(value);
+}
+function globToRegex(pattern) {
+  let i = 0;
+  let re = "^";
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === "*" && pattern[i + 1] === "*") {
+      if (i === 0 && pattern[i + 2] === "/") {
+        re += "(.*\\/)?";
+        i += 3;
+      } else {
+        re += ".*";
+        i += 2;
+        if (pattern[i] === "/") i++;
+      }
+    } else if (ch === "*") {
+      re += "[^/]*";
+      i++;
+    } else if (ch === "?") {
+      re += "[^/]";
+      i++;
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+      i++;
+    }
+  }
+  return new RegExp(re + "$");
+}
+
+// src/sorter.ts
+function sortGroup(imports) {
+  return [...imports].sort((a, b) => {
+    if (a.importKind === "type" && b.importKind !== "type") return -1;
+    if (a.importKind !== "type" && b.importKind === "type") return 1;
+    return a.specifier.localeCompare(b.specifier);
+  });
+}
+function sortNamedImports(node) {
+  const sorted = [...node.namedImports].sort((a, b) => {
+    if (a.kind === "type" && b.kind !== "type") return -1;
+    if (a.kind !== "type" && b.kind === "type") return 1;
+    return a.name.localeCompare(b.name);
+  });
+  return { ...node, namedImports: sorted };
+}
+
+// src/printer.ts
+function detectQuoteChar(source) {
+  const m = source.match(/from\s*(["'])/);
+  return m?.[1] === '"' ? '"' : "'";
+}
+function printImportNode(node, q = "'") {
+  return buildImportStatement(node, q);
+}
+function printGroups(groups, config, q = "'") {
+  const useComments = config.groupComments !== false;
+  const useSeparator = config.groupSeparator !== false;
+  const parts = [];
+  for (const group of groups) {
+    const importLines = [];
+    for (let i = 0; i < group.imports.length; i++) {
+      const node = group.imports[i];
+      if (i === 0 && useComments) {
+        importLines.push(`// ${group.name}
+${buildImportStatement(node, q)}`);
+        continue;
+      }
+      importLines.push(printImportNode(node, q));
+    }
+    parts.push(importLines.join("\n"));
+  }
+  return parts.join(useSeparator ? "\n\n" : "\n");
+}
+function buildImportStatement(node, q) {
+  if (node.isSideEffect) {
+    return `import ${q}${node.specifier}${q};`;
+  }
+  const typePrefix = node.importKind === "type" ? "type " : "";
+  const parts = [];
+  if (node.defaultImport) {
+    parts.push(node.defaultImport);
+  }
+  if (node.namespaceImport) {
+    parts.push(`* as ${node.namespaceImport}`);
+  }
+  if (node.namedImports.length > 0) {
+    const named = node.namedImports.map((n) => {
+      const typePrefix2 = n.kind === "type" ? "type " : "";
+      return n.alias ? `${typePrefix2}${n.name} as ${n.alias}` : `${typePrefix2}${n.name}`;
+    }).join(", ");
+    parts.push(`{ ${named} }`);
+  }
+  return `import ${typePrefix}${parts.join(", ")} from ${q}${node.specifier}${q};`;
+}
+
+// src/format.ts
+function collectOrphanSegments(source, imports) {
+  const orphans = [];
+  for (let i = 0; i < imports.length - 1; i++) {
+    const gapStart = imports[i].end;
+    const gapEnd = imports[i + 1].start;
+    if (gapEnd <= gapStart) continue;
+    let gap = source.slice(gapStart, gapEnd);
+    const nextComment = imports[i + 1].attachedComment;
+    if (nextComment) {
+      const commentText = nextComment.startsWith("//") ? nextComment.slice(2) : nextComment;
+      const commentPattern = `// ${commentText.trim()}`;
+      const idx = gap.lastIndexOf(commentPattern);
+      if (idx !== -1) gap = gap.slice(0, idx);
+    }
+    const trimmed = gap.trim();
+    if (trimmed) orphans.push(trimmed);
+  }
+  return orphans;
+}
+function formatImports(source, config, options = {}) {
+  const imports = parseImports(source);
+  if (imports.length === 0) return source;
+  const orphans = collectOrphanSegments(source, imports);
+  const clean = imports.map((n) => ({ ...n, attachedComment: void 0 }));
+  const deduped = deduplicateImports(clean);
+  const sorted = deduped.map(sortNamedImports);
+  const grouped = groupImports(sorted, config, options);
+  const sortedGroups = grouped.map((g) => ({ ...g, imports: sortGroup(g.imports) }));
+  const q = detectQuoteChar(source);
+  const newImportBlock = printGroups(sortedGroups, config, q);
+  const firstImport = imports[0];
+  const lastImport = imports[imports.length - 1];
+  let regionStart = firstImport.start;
+  if (firstImport.attachedComment) {
+    const before2 = source.slice(0, firstImport.start);
+    const commentLineStart = before2.lastIndexOf("\n", before2.length - 2) + 1;
+    regionStart = commentLineStart;
+  }
+  let regionEnd = lastImport.end;
+  if (source[regionEnd] === "\n") regionEnd++;
+  const before = source.slice(0, regionStart);
+  const after = source.slice(regionEnd);
+  const orphanSuffix = orphans.length > 0 ? "\n" + orphans.join("\n") + "\n" : "";
+  return before + newImportBlock + "\n" + orphanSuffix + after;
+}
+
+// cli.ts
+var HELP = `
+apotheke \u2014 JavaScript/TypeScript import organizer
+
+Usage:
+  apotheke --write <files...>           Organize imports in place
+  apotheke --check <files...>           Exit 1 if any file would change (CI)
+  apotheke --diff <files...>            Print what would change
+  apotheke --stdin-filepath <file>      Read from stdin, write to stdout
+
+Options:
+  --config <path>    Path to config file (default: auto-discover apotheke.config.mjs/.js)
+  --help             Show this help
+
+Examples:
+  apotheke --write src/**/*.tsx
+  apotheke --check src/**/*.ts
+  echo "import..." | apotheke --stdin-filepath src/app.tsx
+`.trim();
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes("--help")) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const mode = args.find((a) => ["--write", "--check", "--diff", "--stdin-filepath"].includes(a));
+  if (!mode) {
+    console.error("Error: specify --write, --check, --diff, or --stdin-filepath\n");
+    console.log(HELP);
+    process.exit(1);
+  }
+  const configIdx = args.indexOf("--config");
+  const explicitConfig = configIdx >= 0 ? args[configIdx + 1] : void 0;
+  if (mode === "--stdin-filepath") {
+    const filepath = args[args.indexOf("--stdin-filepath") + 1];
+    if (!filepath) {
+      console.error("Error: --stdin-filepath requires a file path argument");
+      process.exit(1);
+    }
+    const source = await readStdin();
+    const config = await resolveConfig(filepath, explicitConfig);
+    const result = formatImports(source, config, {
+      fileDir: path3.dirname(path3.resolve(filepath)),
+      rootDir: findRootDir(filepath)
+    });
+    process.stdout.write(result);
+    return;
+  }
+  const modeIdx = args.indexOf(mode);
+  const fileArgs = [];
+  for (let i = modeIdx + 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--config") {
+      i++;
+      continue;
+    }
+    if (!arg.startsWith("--")) fileArgs.push(arg);
+  }
+  if (fileArgs.length === 0) {
+    console.error("Error: no files specified");
+    process.exit(1);
+  }
+  const files = await expandGlobs(fileArgs);
+  let anyChanged = false;
+  for (const file of files) {
+    const source = fs.readFileSync(file, "utf-8");
+    const config = await resolveConfig(file, explicitConfig);
+    const result = formatImports(source, config, {
+      fileDir: path3.dirname(path3.resolve(file)),
+      rootDir: findRootDir(file)
+    });
+    if (result === source) continue;
+    anyChanged = true;
+    if (mode === "--write") {
+      fs.writeFileSync(file, result, "utf-8");
+      console.log(`  formatted ${file}`);
+    } else if (mode === "--diff") {
+      printDiff(file, source, result);
+    } else if (mode === "--check") {
+      console.log(`  needs formatting: ${file}`);
+    }
+  }
+  if (mode === "--check" && anyChanged) process.exit(1);
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function resolveConfig(filePath, explicitConfig) {
+  if (explicitConfig) {
+    return loadConfig(path3.resolve(explicitConfig));
+  }
+  let dir = path3.dirname(path3.resolve(filePath));
+  while (true) {
+    for (const name of ["apotheke.config.mjs", "apotheke.config.js"]) {
+      const candidate = path3.join(dir, name);
+      if (fs.existsSync(candidate)) {
+        return loadConfig(candidate);
+      }
+    }
+    const parent = path3.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `apotheke: no config found for ${filePath}. Create an apotheke.config.mjs in your project root.`
+  );
+}
+function findRootDir(filePath) {
+  let dir = path3.dirname(path3.resolve(filePath));
+  while (true) {
+    if (fs.existsSync(path3.join(dir, "package.json"))) return dir;
+    const parent = path3.dirname(dir);
+    if (parent === dir) return dir;
+    dir = parent;
+  }
+}
+async function expandGlobs(patterns) {
+  const cwd = process.cwd();
+  const submoduleDirs = getSubmoduleDirs(cwd);
+  const files = [];
+  for (const pattern of patterns) {
+    if (!/[*?{[]/.test(pattern)) {
+      const abs = path3.resolve(pattern);
+      if (/\.(tsx?|jsx?)$/.test(abs) && fs.existsSync(abs) && !isUnderSubmodule(abs, submoduleDirs)) {
+        files.push(abs);
+      }
+      continue;
+    }
+    const matches2 = await fg(pattern, { cwd, onlyFiles: true, absolute: true });
+    for (const abs of matches2) {
+      if (/\.(tsx?|jsx?)$/.test(abs) && !isUnderSubmodule(abs, submoduleDirs)) {
+        files.push(abs);
+      }
+    }
+  }
+  return [...new Set(files)];
+}
+function getSubmoduleDirs(cwd) {
+  try {
+    const output = execFileSync("git", ["-C", cwd, "submodule", "foreach", "--recursive", "--quiet", "pwd"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    return output.trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+function isUnderSubmodule(filePath, submoduleDirs) {
+  return submoduleDirs.some(
+    (dir) => filePath === dir || filePath.startsWith(dir + path3.sep)
+  );
+}
+function printDiff(file, original, updated) {
+  const origLines = original.split("\n");
+  const newLines = updated.split("\n");
+  console.log(`--- ${file}`);
+  console.log(`+++ ${file}`);
+  const maxLen = Math.max(origLines.length, newLines.length);
+  for (let i = 0; i < maxLen; i++) {
+    const o = origLines[i];
+    const n = newLines[i];
+    if (o !== n) {
+      if (o !== void 0) console.log(`- ${o}`);
+      if (n !== void 0) console.log(`+ ${n}`);
+    }
+  }
+}
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+interface GroupConfig {
+    name: string;
+    match: string[];
+}
+interface ApothekeConfig {
+    extends?: string;
+    groups: GroupConfig[];
+    aliases?: Record<string, string>;
+    baseUrl?: string;
+    normalizeImports?: 'alias' | 'relative' | 'absolute' | false;
+    groupSeparator?: boolean;
+    groupComments?: boolean;
+}
+
+interface FormatOptions {
+    fileDir?: string;
+    rootDir?: string;
+}
+declare function formatImports(source: string, config: ApothekeConfig, options?: FormatOptions): string;
+
+/**
+ * Apotheke — prettier plugin + programmatic API
+ *
+ * Prettier plugin usage (.prettierrc):
+ *   { "plugins": ["apotheke"] }
+ *
+ * Requirements: prettier v3+, Bun runtime
+ *
+ * The plugin runs as a `preprocess` step, so apotheke organises imports
+ * first and prettier formats the result — correct order, one pass.
+ *
+ * Pre-commit (lint-staged, prettier v2):
+ *   { "*.{ts,tsx}": ["apotheke --write", "prettier --write"] }
+ */
+type PrettierParser = {
+    preprocess?: (text: string, opts: {
+        filepath?: string;
+    }) => string | Promise<string>;
+    parse?: (text: string, options: unknown) => unknown;
+    astFormat?: string;
+    locStart?: (node: unknown) => number;
+    locEnd?: (node: unknown) => number;
+    [k: string]: unknown;
+};
+declare const parsers: {
+    typescript: PrettierParser;
+    babel: PrettierParser;
+    "babel-ts": PrettierParser;
+    "babel-flow": PrettierParser;
+};
+
+export { type ApothekeConfig, formatImports, parsers };

package/dist/index.js

@@ -0,0 +1,453 @@
+// index.ts
+import path3 from "path";
+import { existsSync as existsSync2 } from "fs";
+
+// src/parser.ts
+import { parseSync } from "oxc-parser";
+function parseImports(source) {
+  const result = parseSync("file.tsx", source);
+  const comments = result.comments;
+  const nodes = [];
+  for (const node of result.program.body) {
+    if (node.type !== "ImportDeclaration") continue;
+    const specifier = node.source.value;
+    let defaultImport;
+    const namedImports = [];
+    let namespaceImport;
+    for (const s of node.specifiers) {
+      if (s.type === "ImportDefaultSpecifier") {
+        defaultImport = s.local.name;
+      } else if (s.type === "ImportNamespaceSpecifier") {
+        namespaceImport = s.local.name;
+      } else if (s.type === "ImportSpecifier") {
+        const imported = s.imported;
+        const name = imported.type === "Identifier" ? imported.name : imported.value;
+        const localName = s.local.name;
+        const kind = s.importKind === "type" ? "type" : "value";
+        const named = { name, kind };
+        if (localName !== name) named.alias = localName;
+        namedImports.push(named);
+      }
+    }
+    const importKind = node.importKind === "type" ? "type" : "value";
+    const isSideEffect = node.specifiers.length === 0 && importKind === "value";
+    const importNode = {
+      specifier,
+      namedImports,
+      isSideEffect,
+      importKind,
+      start: node.start,
+      end: node.end
+    };
+    if (defaultImport) importNode.defaultImport = defaultImport;
+    if (namespaceImport) importNode.namespaceImport = namespaceImport;
+    const attached = findAttachedComment(source, node.start, comments);
+    if (attached) importNode.attachedComment = attached;
+    nodes.push(importNode);
+  }
+  return nodes;
+}
+function findAttachedComment(source, importStart, comments) {
+  const linesBefore = source.slice(0, importStart).split("\n");
+  const importLine = linesBefore.length - 1;
+  for (const comment of comments) {
+    if (comment.type !== "Line") continue;
+    const commentLines = source.slice(0, comment.end).split("\n");
+    const commentLine = commentLines.length - 1;
+    if (commentLine === importLine - 1) {
+      return `//${comment.value}`;
+    }
+  }
+  return void 0;
+}
+
+// src/deduplicator.ts
+function deduplicateImports(imports) {
+  const map = /* @__PURE__ */ new Map();
+  for (const node of imports) {
+    const key = `${node.importKind}::${node.specifier}`;
+    if (!map.has(key)) {
+      map.set(key, { ...node, namedImports: [...node.namedImports] });
+      continue;
+    }
+    const existing = map.get(key);
+    if (node.defaultImport && !existing.defaultImport) {
+      existing.defaultImport = node.defaultImport;
+    }
+    if (node.namespaceImport && !existing.namespaceImport) {
+      existing.namespaceImport = node.namespaceImport;
+    }
+    for (const named of node.namedImports) {
+      if (!existing.namedImports.some((n) => n.name === named.name && n.kind === named.kind)) {
+        existing.namedImports.push(named);
+      }
+    }
+    existing.isSideEffect = !existing.defaultImport && !existing.namespaceImport && existing.namedImports.length === 0;
+  }
+  return Array.from(map.values());
+}
+
+// src/grouper.ts
+import path from "path";
+function groupImports(imports, config, options = {}) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const node of imports) {
+    const groupName = assignGroup(node, config, options);
+    if (!buckets.has(groupName)) buckets.set(groupName, []);
+    buckets.get(groupName).push(node);
+  }
+  const result = [];
+  if (buckets.has("SideEffects")) {
+    result.push({ name: "SideEffects", imports: buckets.get("SideEffects") });
+  }
+  for (const group of config.groups) {
+    if (buckets.has(group.name)) {
+      result.push({ name: group.name, imports: buckets.get(group.name) });
+    }
+  }
+  if (buckets.has("Others")) {
+    result.push({ name: "Others", imports: buckets.get("Others") });
+  }
+  return result;
+}
+function assignGroup(node, config, options) {
+  if (node.isSideEffect) return "SideEffects";
+  const canonicalPath = resolveCanonicalPath(node.specifier, config, options);
+  for (const group of config.groups) {
+    for (const pattern of group.match) {
+      if (matches(node.specifier, pattern)) return group.name;
+      if (canonicalPath && matches(canonicalPath, pattern)) return group.name;
+    }
+  }
+  return "Others";
+}
+function resolveCanonicalPath(specifier, config, options) {
+  if (specifier.startsWith(".") || specifier.startsWith("/")) {
+    const base = options.fileDir ?? process.cwd();
+    return path.resolve(base, specifier);
+  }
+  const aliases = config.aliases ?? {};
+  for (const [alias, target] of Object.entries(aliases)) {
+    const prefix = alias.endsWith("/") ? alias : `${alias}/`;
+    if (specifier === alias || specifier.startsWith(prefix)) {
+      const rest = specifier.slice(prefix.length);
+      const root = options.rootDir ?? process.cwd();
+      const resolved = path.resolve(root, target, rest);
+      return resolved;
+    }
+  }
+  return null;
+}
+function matches(value, pattern) {
+  return globToRegex(pattern).test(value);
+}
+function globToRegex(pattern) {
+  let i = 0;
+  let re = "^";
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === "*" && pattern[i + 1] === "*") {
+      if (i === 0 && pattern[i + 2] === "/") {
+        re += "(.*\\/)?";
+        i += 3;
+      } else {
+        re += ".*";
+        i += 2;
+        if (pattern[i] === "/") i++;
+      }
+    } else if (ch === "*") {
+      re += "[^/]*";
+      i++;
+    } else if (ch === "?") {
+      re += "[^/]";
+      i++;
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+      i++;
+    }
+  }
+  return new RegExp(re + "$");
+}
+
+// src/sorter.ts
+function sortGroup(imports) {
+  return [...imports].sort((a, b) => {
+    if (a.importKind === "type" && b.importKind !== "type") return -1;
+    if (a.importKind !== "type" && b.importKind === "type") return 1;
+    return a.specifier.localeCompare(b.specifier);
+  });
+}
+function sortNamedImports(node) {
+  const sorted = [...node.namedImports].sort((a, b) => {
+    if (a.kind === "type" && b.kind !== "type") return -1;
+    if (a.kind !== "type" && b.kind === "type") return 1;
+    return a.name.localeCompare(b.name);
+  });
+  return { ...node, namedImports: sorted };
+}
+
+// src/printer.ts
+function detectQuoteChar(source) {
+  const m = source.match(/from\s*(["'])/);
+  return m?.[1] === '"' ? '"' : "'";
+}
+function printImportNode(node, q = "'") {
+  return buildImportStatement(node, q);
+}
+function printGroups(groups, config, q = "'") {
+  const useComments = config.groupComments !== false;
+  const useSeparator = config.groupSeparator !== false;
+  const parts = [];
+  for (const group of groups) {
+    const importLines = [];
+    for (let i = 0; i < group.imports.length; i++) {
+      const node = group.imports[i];
+      if (i === 0 && useComments) {
+        importLines.push(`// ${group.name}
+${buildImportStatement(node, q)}`);
+        continue;
+      }
+      importLines.push(printImportNode(node, q));
+    }
+    parts.push(importLines.join("\n"));
+  }
+  return parts.join(useSeparator ? "\n\n" : "\n");
+}
+function buildImportStatement(node, q) {
+  if (node.isSideEffect) {
+    return `import ${q}${node.specifier}${q};`;
+  }
+  const typePrefix = node.importKind === "type" ? "type " : "";
+  const parts = [];
+  if (node.defaultImport) {
+    parts.push(node.defaultImport);
+  }
+  if (node.namespaceImport) {
+    parts.push(`* as ${node.namespaceImport}`);
+  }
+  if (node.namedImports.length > 0) {
+    const named = node.namedImports.map((n) => {
+      const typePrefix2 = n.kind === "type" ? "type " : "";
+      return n.alias ? `${typePrefix2}${n.name} as ${n.alias}` : `${typePrefix2}${n.name}`;
+    }).join(", ");
+    parts.push(`{ ${named} }`);
+  }
+  return `import ${typePrefix}${parts.join(", ")} from ${q}${node.specifier}${q};`;
+}
+
+// src/format.ts
+function collectOrphanSegments(source, imports) {
+  const orphans = [];
+  for (let i = 0; i < imports.length - 1; i++) {
+    const gapStart = imports[i].end;
+    const gapEnd = imports[i + 1].start;
+    if (gapEnd <= gapStart) continue;
+    let gap = source.slice(gapStart, gapEnd);
+    const nextComment = imports[i + 1].attachedComment;
+    if (nextComment) {
+      const commentText = nextComment.startsWith("//") ? nextComment.slice(2) : nextComment;
+      const commentPattern = `// ${commentText.trim()}`;
+      const idx = gap.lastIndexOf(commentPattern);
+      if (idx !== -1) gap = gap.slice(0, idx);
+    }
+    const trimmed = gap.trim();
+    if (trimmed) orphans.push(trimmed);
+  }
+  return orphans;
+}
+function formatImports(source, config, options = {}) {
+  const imports = parseImports(source);
+  if (imports.length === 0) return source;
+  const orphans = collectOrphanSegments(source, imports);
+  const clean = imports.map((n) => ({ ...n, attachedComment: void 0 }));
+  const deduped = deduplicateImports(clean);
+  const sorted = deduped.map(sortNamedImports);
+  const grouped = groupImports(sorted, config, options);
+  const sortedGroups = grouped.map((g) => ({ ...g, imports: sortGroup(g.imports) }));
+  const q = detectQuoteChar(source);
+  const newImportBlock = printGroups(sortedGroups, config, q);
+  const firstImport = imports[0];
+  const lastImport = imports[imports.length - 1];
+  let regionStart = firstImport.start;
+  if (firstImport.attachedComment) {
+    const before2 = source.slice(0, firstImport.start);
+    const commentLineStart = before2.lastIndexOf("\n", before2.length - 2) + 1;
+    regionStart = commentLineStart;
+  }
+  let regionEnd = lastImport.end;
+  if (source[regionEnd] === "\n") regionEnd++;
+  const before = source.slice(0, regionStart);
+  const after = source.slice(regionEnd);
+  const orphanSuffix = orphans.length > 0 ? "\n" + orphans.join("\n") + "\n" : "";
+  return before + newImportBlock + "\n" + orphanSuffix + after;
+}
+
+// src/config.ts
+import path2 from "path";
+import { existsSync, readFileSync } from "fs";
+function mergeConfigs(parent, child) {
+  const mergedGroups = [...parent.groups];
+  for (const childGroup of child.groups ?? []) {
+    const existingIdx = mergedGroups.findIndex((g) => g.name === childGroup.name);
+    if (existingIdx >= 0) {
+      mergedGroups[existingIdx] = childGroup;
+    } else {
+      mergedGroups.push(childGroup);
+    }
+  }
+  return {
+    ...parent,
+    ...child,
+    groups: mergedGroups,
+    aliases: { ...parent.aliases ?? {}, ...child.aliases ?? {} }
+  };
+}
+async function loadConfig(configPath) {
+  const mod = await import(configPath);
+  const userConfig = mod.default ?? mod;
+  const configDir = path2.dirname(configPath);
+  const config = { ...userConfig };
+  const tsconfig = loadTsConfig(configDir);
+  if (tsconfig) {
+    const opts = tsconfig.compilerOptions ?? {};
+    if (opts.baseUrl && !config.baseUrl) {
+      config.baseUrl = opts.baseUrl;
+    }
+    if (opts.paths) {
+      const aliases = { ...config.aliases ?? {} };
+      for (const [aliasPattern, targets] of Object.entries(
+        opts.paths
+      )) {
+        const alias = aliasPattern.replace(/\/\*$/, "");
+        const target = (targets[0] ?? "").replace(/\/\*$/, "");
+        if (!aliases[alias]) aliases[alias] = target;
+      }
+      config.aliases = aliases;
+    }
+  }
+  if (userConfig.extends) {
+    const parentPath = path2.resolve(configDir, userConfig.extends);
+    if (!existsSync(parentPath)) {
+      throw new Error(
+        `apotheke: extended config not found: ${parentPath}
+  (referenced from ${configPath} via "extends": "${userConfig.extends}")`
+      );
+    }
+    const parent = await loadConfig(parentPath);
+    return mergeConfigs(parent, config);
+  }
+  return config;
+}
+function loadTsConfig(dir) {
+  const tsconfigPath = path2.join(dir, "tsconfig.json");
+  if (!existsSync(tsconfigPath)) return null;
+  try {
+    const text = readFileSync(tsconfigPath, "utf8");
+    const cleaned = text.replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    return JSON.parse(cleaned);
+  } catch {
+    return null;
+  }
+}
+
+// index.ts
+import { createRequire } from "module";
+async function resolveConfig(filePath) {
+  const candidates = ["apotheke.config.mjs", "apotheke.config.js"];
+  let dir = path3.dirname(path3.resolve(filePath));
+  while (true) {
+    for (const name of candidates) {
+      const candidate = path3.join(dir, name);
+      if (existsSync2(candidate)) return loadConfig(candidate);
+    }
+    const parent = path3.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `apotheke: no config found for ${filePath}. Create an apotheke.config.mjs in your project root.`
+  );
+}
+async function preprocess(text, options) {
+  try {
+    const config = await resolveConfig(options.filepath ?? process.cwd());
+    const fileDir = options.filepath ? path3.dirname(path3.resolve(options.filepath)) : void 0;
+    return formatImports(text, config, { fileDir });
+  } catch {
+    return text;
+  }
+}
+function resolveBaseParser(pluginPath, parserName, startDir) {
+  let dir = startDir;
+  while (true) {
+    try {
+      const req = createRequire(path3.join(dir, "__placeholder__.js"));
+      const mod = req(pluginPath);
+      const base = mod.parsers?.[parserName];
+      if (base) return base;
+    } catch {
+    }
+    const parent = path3.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function makeParser(pluginPath, parserName) {
+  let cached = void 0;
+  function getBase(filepath) {
+    if (cached) return cached;
+    const roots = [
+      filepath ? path3.dirname(path3.resolve(filepath)) : null,
+      process.cwd()
+    ].filter(Boolean);
+    for (const root of roots) {
+      const found = resolveBaseParser(pluginPath, parserName, root);
+      if (found) {
+        cached = found;
+        return cached;
+      }
+    }
+    return null;
+  }
+  getBase();
+  return {
+    // astFormat must always be present so prettier can find its printer before
+    // parse() is called. "estree" is correct for all four parsers we expose.
+    astFormat: "estree",
+    // locStart/locEnd must match the base parser exactly. By the time prettier
+    // calls these, parse() has already run and populated `cached`, so we always
+    // delegate to the real implementations rather than approximating them.
+    locStart(node) {
+      return (cached?.locStart ?? ((n) => n.start))(node);
+    },
+    locEnd(node) {
+      return (cached?.locEnd ?? ((n) => n.end))(node);
+    },
+    parse(text, options) {
+      const base = getBase(options?.filepath);
+      if (base?.parse) {
+        return base.parse(text, options);
+      }
+      throw new Error(
+        `apotheke: could not resolve ${parserName} parser from prettier. Make sure prettier is installed in your project.`
+      );
+    },
+    async preprocess(text, opts) {
+      const base = getBase(opts?.filepath);
+      const basePreprocess = base?.preprocess;
+      const after = basePreprocess ? await basePreprocess(text, opts) : text;
+      return preprocess(after, opts);
+    }
+  };
+}
+var parsers = {
+  typescript: makeParser("prettier/plugins/typescript", "typescript"),
+  babel: makeParser("prettier/plugins/babel", "babel"),
+  "babel-ts": makeParser("prettier/plugins/babel", "babel-ts"),
+  "babel-flow": makeParser("prettier/plugins/babel", "babel-flow")
+};
+export {
+  formatImports,
+  parsers
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "apotheke",
+  "version": "0.0.1",
+  "description": "JavaScript/TypeScript import organizer — prettier plugin + CLI",
+  "type": "module",
+  "repository": {
+    "url": "https://github.com/mRaffaello/apotheke"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "apotheke": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.3",
+    "@commitlint/config-conventional": "^20.5.3",
+    "@types/node": "^25.6.0",
+    "husky": "^9.1.7",
+    "prettier": "^3.8.3",
+    "tsup": "^8.5.1",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "prettier": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "prettier": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "oxc-parser": "^0.129.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:e2e": "vitest run tests/e2e/e2e.test.ts"
+  }
+}