importmapify 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+===========
+
+Copyright (c) 2026 Kaj Kowalski
+
+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,158 @@
+# importmapify
+
+[![NPM](https://img.shields.io/npm/v/importmapify?logo=npm&labelColor=CB3837&color=black)][npm]
+[![CI](https://github.com/kjanat/importmapify/actions/workflows/publish.yml/badge.svg)][ci]
+[![Socket](https://badge.socket.dev/npm/package/importmapify)][socket]
+
+Expand `package.json` subpath-pattern imports into the explicit entries a
+[Deno import map] needs.
+
+Node resolves subpath patterns like `#lib/*` -> `./src/lib/*.ts` internally.
+Deno's import maps only support exact keys and trailing-slash prefixes, so
+tools that expect an import map (`deno doc`, `deno check`, the Deno LSP) need
+one entry per matched source file instead. This package performs that
+expansion and writes a deterministically sorted import map.
+
+[Deno import map]: https://docs.deno.com/runtime/fundamentals/modules/#differentiating-between-imports-or-importmap-in-deno.json-and---import-map-option
+[ci]: https://github.com/kjanat/importmapify/actions/workflows/publish.yml
+[npm]: https://npm.im/importmapify
+[socket]: https://socket.dev/npm/package/importmapify
+
+## Install
+
+```sh
+npm install importmapify
+```
+
+## CLI
+
+```sh
+npx importmapify --root . --out deno.import_map.json
+```
+
+| Flag                 | Alias | Meaning                                                           | Default                |
+| -------------------- | ----- | ----------------------------------------------------------------- | ---------------------- |
+| `--root`             | `-r`  | Project root containing the manifest                              | current directory      |
+| `--manifest`         | `-m`  | Manifest path, relative to root                                   | `package.json`         |
+| `--out`              | `-o`  | Output path, relative to root                                     | `deno.import_map.json` |
+| `--import key=value` | `-i`  | Extra import entry; repeatable                                    | none                   |
+| `--condition name`   | `-c`  | Condition tried when a target is a conditional object; repeatable | `import`, `default`    |
+| `--check`            |       | Exit 1 if the output file is stale, without writing it            | off                    |
+| `--stdout`           |       | Print the map instead of writing it                               | off                    |
+
+Run `npx importmapify --help` for the full reference, or `npx importmapify
+completions` for shell completions.
+
+## Library
+
+```ts
+import { writeImportMap } from 'importmapify';
+
+const out = writeImportMap({
+  root: import.meta.dirname,
+  out: 'deno.import_map.json',
+  additionalImports: {
+    'bun:test': './node_modules/bun-types/test.d.ts',
+  },
+});
+```
+
+| Export            | Signature                                                | Purpose                                                        |
+| ----------------- | -------------------------------------------------------- | -------------------------------------------------------------- |
+| `createImportMap` | `(options: CreateImportMapOptions) => ImportMapDocument` | Build the import map in memory.                                |
+| `formatImportMap` | `(map: ImportMapDocument) => string`                     | Serialize to the canonical sorted, tab-indented JSON text.     |
+| `writeImportMap`  | `(options: WriteImportMapOptions) => string`             | Build, serialize, and write to disk; returns the written path. |
+
+`CreateImportMapOptions`:
+
+| Option              | Meaning                                                                                           | Default                 |
+| ------------------- | ------------------------------------------------------------------------------------------------- | ----------------------- |
+| `root`              | Base directory for the manifest, source targets, and rebasing.                                    | required                |
+| `manifest`          | Manifest path, relative to `root`.                                                                | `package.json`          |
+| `conditions`        | Condition names tried, in order, against conditional targets (`{"import": ..., "default": ...}`). | `['import', 'default']` |
+| `additionalImports` | Extra entries merged in after manifest expansion; these win on key collision.                     | none                    |
+| `relativeTo`        | Directory the written targets are rebased against.                                                | `root`                  |
+
+`WriteImportMapOptions` extends the above with `out`, the output path relative
+to `root`. `writeImportMap` rebases automatically against `out`'s directory,
+so a nested `out` (for example `.cache/maps/deno.import_map.json`) still
+produces targets that resolve correctly from the map's own location.
+
+## What it generates
+
+Given this manifest:
+
+```json
+{
+  "imports": {
+    "#config": "./src/config.ts",
+    "#lib/*": "./src/lib/*.ts"
+  }
+}
+```
+
+and these files:
+
+```text
+src/
+├── config.ts
+└── lib/
+    ├── bytes.ts
+    └── codecs/
+        └── hex.ts
+```
+
+the generated map is:
+
+```json
+{
+  "imports": {
+    "#config": "./src/config.ts",
+    "#lib/bytes": "./src/lib/bytes.ts",
+    "#lib/bytes.ts": "./src/lib/bytes.ts",
+    "#lib/codecs/hex": "./src/lib/codecs/hex.ts",
+    "#lib/codecs/hex.ts": "./src/lib/codecs/hex.ts"
+  }
+}
+```
+
+A key with its own suffix, such as `#lib/*.js` targeting `./src/lib/*.ts`,
+produces both the renamed specifier and the real filename: `#lib/bytes.js`
+and `#lib/bytes.ts`, both pointing at `./src/lib/bytes.ts`.
+
+## Scope and constraints
+
+- Only the manifest's top-level `imports` field is read.
+- Conditional targets resolve via `conditions`, tried in order, recursively.
+  A target matching no condition is skipped.
+- Pattern keys and targets must both contain `*`, or neither should; a
+  mismatch throws.
+- Expandable pattern targets must point to local files beneath `root`.
+  Target directories are scanned recursively; a missing directory produces
+  no entries.
+- Relative targets (`./...`, `../...`) are rebased against `relativeTo`.
+  Bare specifiers, `npm:`/`jsr:`/`node:` specifiers, and absolute URLs pass
+  through unchanged.
+- If exact and expanded entries produce the same key, the later manifest
+  entry wins.
+- Output entries are sorted by UTF-16 code unit for stable diffs.
+
+## Use the generated map
+
+```sh
+deno doc --import-map=deno.import_map.json src/index.ts
+deno check --import-map=deno.import_map.json src/
+deno run --import-map=deno.import_map.json src/main.ts
+```
+
+or reference it once in `deno.json`:
+
+```json
+{
+  "importMap": "./deno.import_map.json"
+}
+```
+
+## License
+
+MIT

package/dist/import-map.mjs

@@ -0,0 +1 @@
+import e from"node:fs";import t from"node:path";function n(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function r(e){let t=e.targetSuffix.split(`*`),r=t[0]??``,i=t.slice(1).map(e=>`\\k<wildcard>${n(e)}`).join(``);return RegExp(`^${n(e.targetPrefix)}(?<wildcard>.*)${n(r)}${i}$`)}function i(e,n){let r=e.indexOf(`*`),i=n.indexOf(`*`);if(r===-1&&i===-1)return;if(r===-1||i===-1)throw Error(`Import pattern mismatch: "${e}" -> "${n}"; both sides must contain "*", or neither should.`);let a=n.slice(0,i),o=a.endsWith(`/`)?a.slice(0,-1):t.posix.dirname(a);return{keyPrefix:e.slice(0,r),keySuffix:e.slice(r+1),targetDirectory:o===``?`.`:o,targetPrefix:a,targetSuffix:n.slice(i+1)}}function a(e,t){let n={},i=r(e),a=e.targetDirectory===`.`?`./`:`${e.targetDirectory}/`;for(let r of t){let t=`${a}${r}`,o=i.exec(t)?.groups?.wildcard;o!==void 0&&(n[`${e.keyPrefix}${o}${e.keySuffix}`]=t,n[`${e.keyPrefix}${r}`]=t)}return n}function o(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function s(e,t){if(typeof e==`string`)return e;if(o(e))for(let n of t){if(!(n in e))continue;let r=s(e[n],t);if(r!==void 0)return r}}function c(e){return e.startsWith(`./`)||e.startsWith(`../`)}function l(e,n,r){if(!c(r))return r;let i=t.resolve(e,r),a=t.relative(n,i).split(t.sep).join(`/`);return a.startsWith(`.`)?a:`./${a}`}const u=[`import`,`default`];function d(n,r=``){if(!e.existsSync(n))return[];let i=[];for(let a of e.readdirSync(n,{withFileTypes:!0})){let e=r===``?a.name:`${r}/${a.name}`;a.isDirectory()?i.push(...d(t.join(n,a.name),e)):i.push(e)}return i}function f(t){let n;try{n=e.readFileSync(t,`utf8`)}catch(e){throw Error(`Cannot read manifest at ${t}`,{cause:e})}let r;try{r=JSON.parse(n)}catch(e){throw Error(`Cannot parse manifest at ${t} as JSON`,{cause:e})}if(!o(r))throw Error(`Manifest at ${t} must be a JSON object`);return r}function p(e){let n=f(t.join(e.root,e.manifest??`package.json`)),r=o(n.imports)?n.imports:{},c=e.conditions?.length?e.conditions:u,p=e.relativeTo??e.root,m={},h=(t,n)=>{m[t]=l(e.root,p,n)};for(let[n,o]of Object.entries(r)){let r=typeof o==`string`?o:s(o,c);if(r===void 0)continue;let l=i(n,r);if(l===void 0){h(n,r);continue}let u=t.join(e.root,l.targetDirectory);for(let[e,t]of Object.entries(a(l,d(u))))h(e,t)}for(let[t,n]of Object.entries(e.additionalImports??{}))h(t,n);return{imports:Object.fromEntries(Object.entries(m).sort(([e],[t])=>e<t?-1:+(e>t)))}}function m(e){return`${JSON.stringify(e,null,`	`)}\n`}function h(n){let r=t.join(n.root,n.out),i=n.relativeTo??t.dirname(r),a=p({...n,relativeTo:i});return e.mkdirSync(t.dirname(r),{recursive:!0}),e.writeFileSync(r,m(a)),r}export{m as n,h as r,p as t};

package/dist/importmapify.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import{n as e,r as t,t as n}from"./import-map.mjs";import r from"node:fs";import i from"node:path";import{CLIError as a,cli as o,command as s,flag as c}from"dreamcli";function l(e){let t=e.indexOf(`=`);if(t===-1)throw new a(`--import expects key=value, got "${e}"`,{code:`invalid-import-flag`,exitCode:2});return[e.slice(0,t),e.slice(t+1)]}const u=s(`generate`).description(`Expand package.json subpath-pattern imports into a Deno import map.`).flag(`root`,c.path({mustExist:!0,type:`directory`}).default(process.cwd()).describe(`Project root containing the manifest.`).alias(`r`)).flag(`manifest`,c.string().default(`package.json`).describe(`Manifest path, relative to root.`).alias(`m`)).flag(`out`,c.string().default(`deno.import_map.json`).describe(`Output path, relative to root.`).alias(`o`)).flag(`import`,c.array(c.string()).describe(`Additional import entry as key=value. Repeatable.`).alias(`i`)).flag(`condition`,c.array(c.string()).describe(`Condition to try when a target is a conditional object. Repeatable.`).alias(`c`)).flag(`check`,c.boolean().describe(`Exit 1 if the output file is stale instead of writing it.`)).flag(`stdout`,c.boolean().describe(`Print the import map to stdout instead of writing it.`)).action(({flags:o,out:s})=>{if(o.check&&o.stdout)throw new a(`--check and --stdout are mutually exclusive`,{code:`conflicting-flags`,exitCode:2});let c=o.root,u=i.join(c,o.out),d=i.dirname(u),f=Object.fromEntries((o.import??[]).map(l)),p={root:c,manifest:o.manifest,conditions:o.condition,additionalImports:f,relativeTo:d};if(o.stdout){s.log(e(n(p)));return}if(o.check){let t=e(n(p));if((r.existsSync(u)?r.readFileSync(u,`utf8`):void 0)!==t){s.error(`${u} is stale`),s.setExitCode(1);return}s.log(`${u} is up to date`);return}let m=t({...p,out:o.out});s.log(`Wrote ${m}`)});o(`importmapify`).manifest({from:import.meta.url}).default(u).completions().run();export{};

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+//#region src/import-map.d.ts
+interface ImportMapDocument {
+  readonly imports: Readonly<Record<string, string>>;
+}
+interface CreateImportMapOptions {
+  readonly root: string;
+  readonly manifest?: string;
+  readonly conditions?: readonly string[];
+  readonly additionalImports?: Readonly<Record<string, string>>;
+  readonly relativeTo?: string;
+}
+interface WriteImportMapOptions extends CreateImportMapOptions {
+  readonly out: string;
+}
+declare function createImportMap(options: CreateImportMapOptions): ImportMapDocument;
+declare function formatImportMap(map: ImportMapDocument): string;
+declare function writeImportMap(options: WriteImportMapOptions): string;
+//#endregion
+export { type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, formatImportMap, writeImportMap };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{n as e,r as t,t as n}from"./import-map.mjs";export{n as createImportMap,e as formatImportMap,t as writeImportMap};

package/package.json

@@ -0,0 +1,93 @@
+{
+	"name": "importmapify",
+	"version": "0.1.0",
+	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
+	"keywords": [
+		"deno",
+		"import-map",
+		"importmap",
+		"subpath-imports",
+		"cli",
+		"dreamcli",
+		"ansispeck"
+	],
+	"homepage": "https://github.com/kjanat/importmapify#readme",
+	"bugs": "https://github.com/kjanat/importmapify/issues",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kjanat/importmapify.git"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "Kaj Kowalski",
+		"email": "info@kajkowalski.nl",
+		"url": "https://github.com/kjanat"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"imports": {
+		"#pkg": "./package.json"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"default": "./dist/index.mjs"
+		},
+		"./package.json": "./package.json"
+	},
+	"types": "./dist/index.d.mts",
+	"bin": {
+		"importmapify": "dist/importmapify.mjs"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"bd": "tsdown",
+		"build": "tsdown",
+		"build:watch": "tsdown --watch",
+		"check": "biome check",
+		"check:fix": "biome check --fix",
+		"fmt": "dprint fmt",
+		"lint": "biome lint",
+		"prepack": "bun --bun bd -l error",
+		"prepublishOnly": "[ -n \"${GITHUB_ACTIONS:-}\" ] || { printf '%s\\n' 'manual npm publish blocked; use release workflow for provenance' >&2; exit 1; }",
+		"runbin": "node \"$(jq -r '.bin.[]' package.json)\" --help",
+		"test": "bun test --coverage",
+		"test:coverage": "bun test --coverage",
+		"test:smoke": "node scripts/smoke.mjs",
+		"test:watch": "bun test --watch",
+		"typecheck": "bunx @typescript/native --noEmit"
+	},
+	"dependencies": {
+		"dreamcli": "npm:@kjanat/dreamcli@^3.0.0-rc.9"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/core": "^0.18.5",
+		"@biomejs/biome": "2.5.2 || ^2.5.4",
+		"@types/bun": "^1.3.14",
+		"@types/node": "^26.1.1",
+		"@typescript/native": "npm:typescript@^7",
+		"dprint": "^0.55.2",
+		"publint": "^0.3.21",
+		"sort-package-json": "^4.0.0",
+		"tsdown": "^0.22.7",
+		"typescript": ">=6,<7",
+		"unplugin-unused": "^0.5.7"
+	},
+	"packageManager": "bun@1.3.14",
+	"engines": {
+		"bun": ">=1.3",
+		"node": ">=24"
+	},
+	"volta": {
+		"node": "26.5.0",
+		"npm": "11.18.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true,
+		"registry": "https://registry.npmjs.org/",
+		"tag": "latest"
+	}
+}