apotheke 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,22 @@
-# apotheke
-
-**Prettier for imports.** Deterministic, configurable import organization for
-JavaScript and TypeScript — as a Prettier plugin or a standalone CLI.
-
-📖 **[Documentation](https://marcoraffaello.com/apotheke)**
+<p align="left">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/header/graph.svg?title=apotheke&subtitle=Deterministic%20import%20organization%20for%20JavaScript%20and%20TypeScript&logo=https://raw.githubusercontent.com/mRaffaello/apotheke/main/apps/docs/public/mark-dark.png&align=left&font=geist&mode=dark" />
+    <img alt="apotheke — deterministic import organization for JavaScript and TypeScript" src="https://shieldcn.dev/header/graph.svg?title=apotheke&subtitle=Deterministic%20import%20organization%20for%20JavaScript%20and%20TypeScript&logo=https://raw.githubusercontent.com/mRaffaello/apotheke/main/apps/docs/public/mark.png&align=left&font=geist&mode=light" />
+  </picture>
+</p>
+
+<p align="left">
+  <a href="https://www.npmjs.com/package/apotheke">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/group/npm/apotheke+npm/dm/apotheke+bundlephobia/minzip/apotheke+npm/types/apotheke+github/ci/mRaffaello/apotheke+github/license/mRaffaello/apotheke.svg?variant=secondary&mode=dark" />
+      <img alt="npm version, monthly downloads, minzipped size, TypeScript types, CI status, MIT license" src="https://shieldcn.dev/group/npm/apotheke+npm/dm/apotheke+bundlephobia/minzip/apotheke+npm/types/apotheke+github/ci/mRaffaello/apotheke+github/license/mRaffaello/apotheke.svg?variant=secondary&mode=light" />
+    </picture>
+  </a>
+</p>
+
+**Prettier for imports.** You describe the groups your codebase actually has —
+apotheke sorts every import into them, the same way, in every file. Run it as a
+Prettier plugin or as a standalone CLI.
 
 ```ts
 // Before
@@ -28,72 +41,20 @@ import { useQuery } from '@tanstack/react-query';
 import { createRoute } from '@tanstack/react-router';
 ```
 
-apotheke is not a replacement for Prettier — it runs _inside_ Prettier as a
-`preprocess` plugin, so one `prettier --write` organises imports and formats
-code in a single pass.
+Note where `../api/tsr` and `@tanstack/react-query` landed: grouping is by
+**role in your app**, not by whether a module is local or comes from
+`node_modules`.
 
-## Installation
+## Getting started
 
 ```sh
 pnpm add -D apotheke
 ```
 
-Requires Node.js ≥ 18, and Prettier ≥ 3 if you use the plugin.
-
-## Usage
-
-Describe the groups you want in `apotheke.config.mjs`:
-
-```js
-export default {
-    groups: [
-        { name: 'React', match: ['react', 'react-dom'] },
-        { name: 'Hooks', match: ['**/hooks/**'] },
-        { name: 'Api', match: ['**/api/**', '@tanstack/react-query'] },
-        { name: 'Navigation', match: ['@tanstack/react-router'] }
-    ]
-};
-```
-
-Then either add the Prettier plugin — apotheke must be **last** in the array:
-
-```json
-{ "plugins": ["apotheke"] }
-```
-
-or use the CLI:
-
-```sh
-apotheke --write 'src/**/*.{ts,tsx}'   # rewrite in place
-apotheke --check 'src/**/*.{ts,tsx}'   # CI — exit 1 if anything would change
-apotheke --diff  'src/**/*.{ts,tsx}'   # preview without writing
-```
-
-Groups are matched in order and the first match wins. Unmatched imports collect
-in a trailing `Others` group; side-effect imports always come first. Imports are
-sorted and deduplicated within each group, and `tsconfig.json` path aliases are
-read automatically.
-
-## Documentation
-
-Full guides and reference at
-**[marcoraffaello.com/apotheke](https://marcoraffaello.com/apotheke)**:
-
-- [Configuring groups](https://marcoraffaello.com/apotheke/docs/guides/groups)
-- [Aliases and tsconfig paths](https://marcoraffaello.com/apotheke/docs/guides/aliases)
-- [Monorepos](https://marcoraffaello.com/apotheke/docs/guides/monorepos)
-- [Prettier plugin](https://marcoraffaello.com/apotheke/docs/guides/prettier-plugin)
-- [Config reference](https://marcoraffaello.com/apotheke/docs/reference/config)
+📖 **[Read the documentation →](https://marcoraffaello.com/apotheke)**
 
-## Agent skill
-
-This package ships a `SKILL.md` that teaches a coding agent to scan your
-codebase, propose a group config and wire everything up:
-
-```sh
-mkdir -p .claude/skills/setup-apotheke
-cp node_modules/apotheke/SKILL.md .claude/skills/setup-apotheke/SKILL.md
-```
+The [quick start](https://marcoraffaello.com/apotheke/docs/quick-start) goes
+from an empty config to organised imports in about two minutes.
 
 ## Development
 
@@ -107,6 +68,9 @@ pnpm test             # unit + e2e
 pnpm docs:dev         # run the documentation site locally
 ```
 
+Issues and pull requests are welcome at
+[github.com/mRaffaello/apotheke](https://github.com/mRaffaello/apotheke).
+
 ## License
 
 MIT © Marco Raffaello

package/dist/cli.js

@@ -102,6 +102,12 @@ function deduplicateImports(imports) {
 
 // src/grouper.ts
 import path2 from "path";
+
+// src/types.ts
+var OTHERS_GROUP = "Others";
+var SIDE_EFFECTS_BLOCK = "SideEffects";
+
+// src/grouper.ts
 function groupImports(imports, config, options = {}) {
   const buckets = /* @__PURE__ */ new Map();
   for (const node of imports) {
@@ -110,21 +116,17 @@ function groupImports(imports, config, options = {}) {
     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") });
+  if (buckets.has(OTHERS_GROUP)) {
+    result.push({ name: OTHERS_GROUP, imports: buckets.get(OTHERS_GROUP) });
   }
   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) {
@@ -132,7 +134,7 @@ function assignGroup(node, config, options) {
       if (canonicalPath && matches(canonicalPath, pattern)) return group.name;
     }
   }
-  return "Others";
+  return OTHERS_GROUP;
 }
 function resolveCanonicalPath(specifier, config, options) {
   if (specifier.startsWith(".") || specifier.startsWith("/")) {
@@ -255,9 +257,10 @@ function printGroups(groups, config, q = "'") {
   const parts = [];
   for (const group of groups) {
     const importLines = [];
+    const headed = useComments && group.name !== SIDE_EFFECTS_BLOCK;
     for (let i = 0; i < group.imports.length; i++) {
       const node = group.imports[i];
-      if (i === 0 && useComments) {
+      if (i === 0 && headed) {
         importLines.push(`// ${group.name}
 ${buildImportStatement(node, q)}`);
         continue;
@@ -327,6 +330,35 @@ function collectOrphanSegments(source, imports) {
   }
   return orphans;
 }
+function buildBlocks(imports, config, options) {
+  const blocks = [];
+  let values = [];
+  let sideEffects = [];
+  function flushValues() {
+    if (values.length === 0) return;
+    for (const group of groupImports(values, config, options)) {
+      blocks.push({ ...group, imports: sortGroup(group.imports) });
+    }
+    values = [];
+  }
+  function flushSideEffects() {
+    if (sideEffects.length === 0) return;
+    blocks.push({ name: SIDE_EFFECTS_BLOCK, imports: sideEffects });
+    sideEffects = [];
+  }
+  for (const node of imports) {
+    if (node.isSideEffect) {
+      flushValues();
+      sideEffects.push(node);
+    } else {
+      flushSideEffects();
+      values.push(node);
+    }
+  }
+  flushSideEffects();
+  flushValues();
+  return blocks;
+}
 function formatImports(source, config, options = {}) {
   const imports = parseImports(source);
   if (imports.length === 0) return source;
@@ -334,10 +366,9 @@ function formatImports(source, config, options = {}) {
   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 blocks = buildBlocks(sorted, config, options);
   const q = detectQuoteChar(source);
-  const newImportBlock = printGroups(sortedGroups, config, q);
+  const newImportBlock = printGroups(blocks, config, q);
   const firstImport = imports[0];
   const lastImport = imports[imports.length - 1];
   let regionStart = firstImport.start;

package/dist/index.js

@@ -99,6 +99,12 @@ function deduplicateImports(imports) {
 
 // src/grouper.ts
 import path2 from "path";
+
+// src/types.ts
+var OTHERS_GROUP = "Others";
+var SIDE_EFFECTS_BLOCK = "SideEffects";
+
+// src/grouper.ts
 function groupImports(imports, config, options = {}) {
   const buckets = /* @__PURE__ */ new Map();
   for (const node of imports) {
@@ -107,21 +113,17 @@ function groupImports(imports, config, options = {}) {
     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") });
+  if (buckets.has(OTHERS_GROUP)) {
+    result.push({ name: OTHERS_GROUP, imports: buckets.get(OTHERS_GROUP) });
   }
   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) {
@@ -129,7 +131,7 @@ function assignGroup(node, config, options) {
       if (canonicalPath && matches(canonicalPath, pattern)) return group.name;
     }
   }
-  return "Others";
+  return OTHERS_GROUP;
 }
 function resolveCanonicalPath(specifier, config, options) {
   if (specifier.startsWith(".") || specifier.startsWith("/")) {
@@ -252,9 +254,10 @@ function printGroups(groups, config, q = "'") {
   const parts = [];
   for (const group of groups) {
     const importLines = [];
+    const headed = useComments && group.name !== SIDE_EFFECTS_BLOCK;
     for (let i = 0; i < group.imports.length; i++) {
       const node = group.imports[i];
-      if (i === 0 && useComments) {
+      if (i === 0 && headed) {
         importLines.push(`// ${group.name}
 ${buildImportStatement(node, q)}`);
         continue;
@@ -324,6 +327,35 @@ function collectOrphanSegments(source, imports) {
   }
   return orphans;
 }
+function buildBlocks(imports, config, options) {
+  const blocks = [];
+  let values = [];
+  let sideEffects = [];
+  function flushValues() {
+    if (values.length === 0) return;
+    for (const group of groupImports(values, config, options)) {
+      blocks.push({ ...group, imports: sortGroup(group.imports) });
+    }
+    values = [];
+  }
+  function flushSideEffects() {
+    if (sideEffects.length === 0) return;
+    blocks.push({ name: SIDE_EFFECTS_BLOCK, imports: sideEffects });
+    sideEffects = [];
+  }
+  for (const node of imports) {
+    if (node.isSideEffect) {
+      flushValues();
+      sideEffects.push(node);
+    } else {
+      flushSideEffects();
+      values.push(node);
+    }
+  }
+  flushSideEffects();
+  flushValues();
+  return blocks;
+}
 function formatImports(source, config, options = {}) {
   const imports = parseImports(source);
   if (imports.length === 0) return source;
@@ -331,10 +363,9 @@ function formatImports(source, config, options = {}) {
   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 blocks = buildBlocks(sorted, config, options);
   const q = detectQuoteChar(source);
-  const newImportBlock = printGroups(sortedGroups, config, q);
+  const newImportBlock = printGroups(blocks, config, q);
   const firstImport = imports[0];
   const lastImport = imports[imports.length - 1];
   let regionStart = firstImport.start;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "apotheke",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "Prettier for imports — deterministic import organization as a Prettier plugin or CLI",
     "type": "module",
     "license": "MIT",