importmapify 0.1.0 → 1.0.1

package/README.md

@@ -1,21 +1,20 @@
 # importmapify
 
 [![NPM](https://img.shields.io/npm/v/importmapify?logo=npm&labelColor=CB3837&color=black)][npm]
+[![JSR](https://img.shields.io/jsr/v/@kjanat/importmapify?logoColor=083344&logo=jsr&logoSize=auto&label=&labelColor=f7df1e&color=black)][jsr]
 [![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.
+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.
+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
+[jsr]: https://jsr.io/@kjanat/importmapify
 [socket]: https://socket.dev/npm/package/importmapify
 
 ## Install
@@ -27,21 +26,29 @@ npm install importmapify
 ## CLI
 
 ```sh
-npx importmapify --root . --out deno.import_map.json
+npx importmapify --root . --out 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                    |
+| 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                                     | `import_map.json`   |
+| `--import key=value`        | `-i`  | Extra import entry; repeatable                                    | none                |
+| `--scope prefix::key=value` | `-s`  | Scoped import override; 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.
+Add global and test-scoped dependencies from the CLI:
+
+```sh
+npx importmapify \
+  --import 'dreamcli=jsr:@kjanat/dreamcli@^3' \
+  --scope './tests/::dreamcli/testkit=jsr:@kjanat/dreamcli@^3/testkit'
+```
+
+Run `npx importmapify --help` for the full reference, or `npx importmapify --completions bash` for shell completions.
 
 ## Library
 
@@ -50,10 +57,15 @@ import { writeImportMap } from 'importmapify';
 
 const out = writeImportMap({
   root: import.meta.dirname,
-  out: 'deno.import_map.json',
+  out: 'import_map.json',
   additionalImports: {
     'bun:test': './node_modules/bun-types/test.d.ts',
   },
+  scopes: {
+    './tests/': {
+      'dreamcli/testkit': 'jsr:@kjanat/dreamcli@^3/testkit',
+    },
+  },
 });
 ```
 
@@ -71,12 +83,52 @@ const out = writeImportMap({
 | `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                    |
+| `scopes`            | Scope prefixes mapped to scope-specific import overrides.                                         | 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.
+`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/import_map.json`) still produces
+targets that resolve correctly from the map's own location.
+
+### Project-local generator
+
+A checked-in wrapper keeps project-specific dependency and scope mappings in code:
+
+```ts
+#!/usr/bin/env -S deno run -A --no-config
+
+import { writeImportMap } from 'importmapify';
+
+const output = writeImportMap({
+  root: new URL('..', import.meta.url).pathname,
+  out: 'import_map.json',
+  additionalImports: {
+    dreamcli: 'jsr:@kjanat/dreamcli@^3',
+  },
+  scopes: {
+    './tests/': {
+      'dreamcli/testkit': 'jsr:@kjanat/dreamcli@^3/testkit',
+    },
+  },
+});
+
+console.log(`Wrote ${output}`);
+```
+
+Execute the wrapper directly so its `--no-config` shebang can bootstrap a missing map:
+
+```sh
+scripts/generate-importmap.ts
+```
+
+The equivalent explicit command is:
+
+```sh
+deno run -A --no-config scripts/generate-importmap.ts
+```
+
+Do not omit `--no-config`. If `deno.json` references a map that does not exist yet, `deno run` otherwise fails while
+loading configuration, before the generator starts.
 
 ## What it generates
 
@@ -116,43 +168,181 @@ the generated map is:
 }
 ```
 
-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`.
+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.
+- 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.
+- Relative scope prefixes and targets are rebased against `relativeTo`; trailing scope slashes are preserved.
+- Import entries, scope prefixes, and scoped entries are sorted by UTF-16 code unit for stable diffs.
 
 ## Use the generated map
 
+The output is a standard external import map. Deno CLI commands, `deno.json`, editor language servers, and APIs that
+embed Deno tooling can all consume it.
+
+### Deno CLI
+
+Pass the map to any command that accepts `--import-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
+deno doc --import-map=import_map.json src/index.ts
+deno doc --import-map=import_map.json --json src/index.ts
+deno doc --import-map=import_map.json --html --output=docs/api src/index.ts
+deno check --import-map=import_map.json src/
+deno run --import-map=import_map.json src/main.ts
+deno test --import-map=import_map.json
+deno bench --import-map=import_map.json
+deno compile --import-map=import_map.json src/main.ts
+```
+
+### `deno.json`
+
+Reference the map once instead of repeating `--import-map`:
+
+```json
+{
+  "importMap": "./import_map.json",
+  "tasks": {
+    "importmapify": {
+      "command": "npx importmapify",
+      "files": ["package.json", "src/**"],
+      "output": ["import_map.json"]
+    },
+    "check": {
+      "command": "deno check src tests",
+      "dependencies": ["importmapify"]
+    }
+  }
+}
+```
+
+Deno applies the map to CLI commands and its language server whenever that configuration is active. `importMap` is an
+alternative to defining `imports` and `scopes` directly in `deno.json`.
+
+When `importMap` points to a generated file, keep that file available after checkout. Deno validates the path before it
+runs commands, including `deno task`, so a task in the same `deno.json` cannot bootstrap a missing map. Bootstrap with
+an executable `--no-config` wrapper, then use cached Deno tasks for subsequent regeneration.
+
+### Editor LSP
+
+The Deno language server uses the selected import map for diagnostics, completions, hover information, and
+go-to-definition. Enable it in Zed with `.zed/settings.json`:
+
+```json
+{
+  "languages": {
+    "TypeScript": {
+      "language_servers": ["deno", "!typescript-language-server", "!vtsls"]
+    }
+  },
+  "lsp": {
+    "deno": {
+      "settings": {
+        "deno": {
+          "enable": true,
+          "config": "./deno.json",
+          "importMap": "./import_map.json"
+        }
+      }
+    }
+  }
+}
 ```
 
-or reference it once in `deno.json`:
+In mixed-runtime repositories, restrict Deno to the relevant paths:
 
 ```json
 {
-  "importMap": "./deno.import_map.json"
+  "lsp": {
+    "deno": {
+      "settings": {
+        "deno": {
+          "enable": true,
+          "enablePaths": ["./src", "./scripts", "./tests"],
+          "config": "./deno.json",
+          "importMap": "./import_map.json"
+        }
+      }
+    }
+  }
+}
+```
+
+Other LSP clients expose the same Deno initialization settings. When the client discovers `deno.json` itself, its
+`importMap` field is usually sufficient without a duplicate editor setting.
+
+### Keep Bun or npm in charge
+
+Reading `package.json` does not make Deno modify it. In a mixed-runtime project, explicitly keep `node_modules` under
+Bun or npm control:
+
+```json
+{
+  "nodeModulesDir": "manual",
+  "importMap": "./import_map.json"
 }
 ```
 
+For full isolation, set `preferPackageJson` to `false` or run with `DENO_NO_PACKAGE_JSON=1`. The generated map must then
+contain every bare dependency and package alias required by the checked files; unresolved entries cannot fall back to
+`package.json`.
+
+### Spawn Deno from Node or Bun
+
+Use the absolute path returned by `writeImportMap` to avoid working-directory ambiguity:
+
+```ts
+import { execFileSync } from 'node:child_process';
+import { writeImportMap } from 'importmapify';
+
+const root = '/path/to/source-tree';
+const importMap = writeImportMap({ root, out: 'import_map.json' });
+
+const documentation = execFileSync(
+  'deno',
+  ['doc', '--import-map', importMap, '--json', 'src/index.ts'],
+  { cwd: root, encoding: 'utf8' },
+);
+```
+
+### `@deno/doc`
+
+The documentation API accepts an import-map file URL:
+
+```ts
+import { doc } from 'jsr:@deno/doc';
+
+const entries = [new URL('./src/index.ts', import.meta.url).href];
+const importMap = new URL('./import_map.json', import.meta.url).href;
+const nodes = await doc(entries, {
+  importMap,
+  printImportMapDiagnostics: false,
+});
+```
+
+## Keep it current
+
+Pattern entries reflect the files present when generation runs. Regenerate after:
+
+- adding, moving, or deleting matching source files;
+- changing `package.json#imports`;
+- changing extra imports or scopes in a wrapper script;
+- updating dependency versions embedded in generated mappings.
+
+Useful generation points include install or prepare hooks, documentation/type-check/test tasks, editor tasks, and CI
+before Deno tooling. Commit the generated map whenever `deno.json#importMap` references it or editor support must work
+immediately after checkout. Ignore it only when bootstrap runs outside that Deno configuration, such as an executable
+`--no-config` wrapper or a Bun/Node lifecycle hook.
+
 ## License
 
 MIT

package/deno.json

@@ -0,0 +1,56 @@
+{
+	"$schema": "https://raw.githubusercontent.com/denoland/deno/refs/heads/main/cli/schemas/config-file.v1.json",
+	"name": "@kjanat/importmapify",
+	"version": "1.0.1",
+	"exports": "./src/mod.ts",
+	"publish": {
+		"include": [
+			"./src/**/*.ts",
+			"./README.md",
+			"./LICENSE",
+			"./deno.json",
+			"./import_map.json",
+			"./package.json"
+		]
+	},
+	"compilerOptions": {
+		"lib": ["ESNext", "DOM", "deno.ns"]
+	},
+	"importMap": "./import_map.json",
+	"license": "MIT",
+	"tasks": {
+		"build": {
+			"description": "build for npm distribution",
+			"command": "bunx tsdown",
+			"files": ["src/**", "package.json", "bun.lock"],
+			"output": ["dist/**", "deno.json"]
+		},
+		"publish": {
+			"command": "deno publish --config deno.json --allow-dirty",
+			"description": "Publish package to jsr",
+			"dependencies": ["importmapify"]
+		},
+		"importmapify": {
+			"description": "generate importmap for deno",
+			"command": "deno run --no-config -A scripts/generate-importmap.ts",
+			"files": ["package.json", "scripts/generate-importmap.ts", "src/**"],
+			"output": ["import_map.json"]
+		}
+	},
+	"lint": {
+		"rules": {
+			"tags": ["recommended", "jsr"]
+		}
+	},
+	"preferPackageJson": false,
+	"homepage": "https://github.com/kjanat/importmapify#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kjanat/importmapify.git"
+	},
+	"lock": false,
+	"jsrDepsInNodeModules": false,
+	"minimumDependencyAge": {
+		"exclude": ["jsr:@kjanat/*", "npm:@kjanat/*"]
+	}
+}

package/dist/mod.d.mts

@@ -0,0 +1,91 @@
+//#region src/map.d.ts
+/** A deterministic Deno import map generated from package import entries. */
+interface ImportMapDocument {
+  /** Exact specifier-to-target mappings, sorted by specifier. */
+  readonly imports: Readonly<Record<string, string>>;
+  /** Scope prefixes mapped to sorted, scope-specific import overrides. */
+  readonly scopes?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+/** Options for creating an import map without writing it to disk. */
+interface CreateImportMapOptions {
+  /** Project directory containing the package manifest. */
+  readonly root: string;
+  /** Manifest path relative to {@link root}. Defaults to `package.json`. */
+  readonly manifest?: string;
+  /** Conditional import keys to try in order. Defaults to `import`, then `default`. */
+  readonly conditions?: readonly string[];
+  /** Explicit entries merged after manifest imports, overriding duplicate keys. */
+  readonly additionalImports?: Readonly<Record<string, string>>;
+  /** Scope-specific import overrides keyed by scope prefix. */
+  readonly scopes?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  /** Directory against which relative targets are rebased. Defaults to {@link root}. */
+  readonly relativeTo?: string;
+}
+/** Options for creating and writing an import map. */
+interface WriteImportMapOptions extends CreateImportMapOptions {
+  /** Output path relative to {@link CreateImportMapOptions.root | root}. */
+  readonly out: string;
+}
+/**
+ * Expand a package's exact and patterned `imports` into a Deno import map.
+ *
+ * Pattern targets are matched against files below {@link CreateImportMapOptions.root | root}.
+ * Conditional targets use the configured condition order, and additional imports are applied last.
+ *
+ * @example Generate entries for the current project.
+ * ```ts
+ * import { createImportMap } from 'jsr:@kjanat/importmapify';
+ *
+ * const map = createImportMap({
+ *   root: Deno.cwd(),
+ *   conditions: ['deno', 'import', 'default'],
+ * });
+ *
+ * console.log(map.imports['#lib/bytes']);
+ * ```
+ *
+ * @param options Project, manifest, condition, and rebasing options.
+ * @returns A sorted import map document.
+ */
+declare function createImportMap(options: CreateImportMapOptions): ImportMapDocument;
+/**
+ * Serialize an import map as stable, tab-indented JSON with a trailing newline.
+ *
+ * @example Format an import map for stdout.
+ * ```ts
+ * import { formatImportMap } from 'jsr:@kjanat/importmapify';
+ *
+ * const text = formatImportMap({
+ *   imports: { '#config': './src/config.ts' },
+ * });
+ *
+ * console.log(text);
+ * ```
+ *
+ * @param map Import map to serialize.
+ * @returns Formatted JSON ready to print or write.
+ */
+declare function formatImportMap(map: ImportMapDocument): string;
+/**
+ * Create an import map and write it to disk, creating parent directories as needed.
+ *
+ * Relative targets are automatically rebased from the project root to the output directory.
+ *
+ * @example Write the conventional Deno import map file.
+ * ```ts
+ * import { writeImportMap } from 'jsr:@kjanat/importmapify';
+ *
+ * const output = writeImportMap({
+ *   root: Deno.cwd(),
+ *   out: 'import_map.json',
+ * });
+ *
+ * console.log(`Wrote ${output}`);
+ * ```
+ *
+ * @param options Creation options plus the output path.
+ * @returns The absolute path of the written file.
+ */
+declare function writeImportMap(options: WriteImportMapOptions): string;
+//#endregion
+export { type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, formatImportMap, writeImportMap };

package/dist/mod.mjs

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+import { CLIError, cli, command, flag } from "dreamcli";
+import fs, { existsSync, readFileSync } from "node:fs";
+import path, { dirname, join } from "node:path";
+import { cwd } from "node:process";
+//#region src/expand.ts
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function targetMatcher(pattern) {
+	const suffixParts = pattern.targetSuffix.split("*");
+	const firstSuffix = suffixParts[0] ?? "";
+	const repeatedSuffixes = suffixParts.slice(1).map((suffix) => `\\k<wildcard>${escapeRegExp(suffix)}`).join("");
+	return new RegExp(`^${escapeRegExp(pattern.targetPrefix)}(?<wildcard>.*)${escapeRegExp(firstSuffix)}${repeatedSuffixes}$`);
+}
+/**
+* Parse matching wildcards from a package import key and target.
+*
+* @example
+* ```ts
+* parsePattern('#lib/*', './src/lib/*.ts');
+* ```
+*
+* @param key Package import specifier pattern.
+* @param target Filesystem target pattern.
+* @returns Parsed pattern components, or `undefined` when neither side contains a wildcard.
+* @throws When only one side contains a wildcard.
+*/
+function parsePattern(key, target) {
+	const keyStar = key.indexOf("*");
+	const targetStar = target.indexOf("*");
+	if (keyStar === -1 && targetStar === -1) return;
+	if (keyStar === -1 || targetStar === -1) throw new Error(`Import pattern mismatch: "${key}" -> "${target}"; both sides must contain "*", or neither should.`);
+	const targetPrefix = target.slice(0, targetStar);
+	const targetDirectory = targetPrefix.endsWith("/") ? targetPrefix.slice(0, -1) : path.posix.dirname(targetPrefix);
+	return {
+		keyPrefix: key.slice(0, keyStar),
+		keySuffix: key.slice(keyStar + 1),
+		targetDirectory: targetDirectory === "" ? "." : targetDirectory,
+		targetPrefix,
+		targetSuffix: target.slice(targetStar + 1)
+	};
+}
+/**
+* Expand a parsed pattern into exact import entries for matching files.
+*
+* @example
+* ```ts
+* const pattern = parsePattern('#lib/*', './src/lib/*.ts');
+* if (pattern) expandPattern(pattern, ['bytes.ts']);
+* ```
+*
+* @param pattern Parsed key and target wildcard components.
+* @param files File paths relative to the pattern's target directory.
+* @returns Exact import specifiers mapped to their source targets.
+*/
+function expandPattern(pattern, files) {
+	const imports = {};
+	const matcher = targetMatcher(pattern);
+	const targetBase = pattern.targetDirectory === "." ? "./" : `${pattern.targetDirectory}/`;
+	for (const file of files) {
+		const target = `${targetBase}${file}`;
+		const wildcard = matcher.exec(target)?.groups?.wildcard;
+		if (wildcard !== void 0) {
+			imports[`${pattern.keyPrefix}${wildcard}${pattern.keySuffix}`] = target;
+			imports[`${pattern.keyPrefix}${file}`] = target;
+		}
+	}
+	return imports;
+}
+/**
+* Determine whether a value is a non-array object record.
+*
+* @param value Value to inspect.
+* @returns Whether the value can be safely read as a string-keyed record.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Resolve a string target from nested conditional import objects.
+*
+* @param value Exact target or conditional target object.
+* @param conditions Condition names to try in priority order.
+* @returns The first matching string target, or `undefined` when none matches.
+*/
+function resolveCondition(value, conditions) {
+	if (typeof value === "string") return value;
+	if (!isRecord(value)) return;
+	for (const condition of conditions) if (condition in value) {
+		const resolved = resolveCondition(value[condition], conditions);
+		if (resolved !== void 0) return resolved;
+	}
+}
+/**
+* Determine whether a target is relative and can be rebased.
+*
+* @param target Import target to inspect.
+* @returns Whether the target starts with `./` or `../`.
+*/
+function isRebasableTarget(target) {
+	return target.startsWith("./") || target.startsWith("../");
+}
+/**
+* Rebase a relative import target from the project root to another directory.
+*
+* Bare specifiers and URL-like targets are returned unchanged.
+*
+* @param root Directory against which the original target is resolved.
+* @param relativeTo Directory from which the returned target should resolve.
+* @param target Import target to rebase.
+* @returns A portable slash-separated target.
+*/
+function rebaseTarget(root, relativeTo, target) {
+	if (!isRebasableTarget(target)) return target;
+	const absolute = path.resolve(root, target);
+	const relative = path.relative(relativeTo, absolute).split(path.sep).join("/");
+	return relative.startsWith(".") ? relative : `./${relative}`;
+}
+//#endregion
+//#region src/map.ts
+const DEFAULT_CONDITIONS = ["import", "default"];
+function filesUnder(dir, prefix = "") {
+	if (!fs.existsSync(dir)) return [];
+	const files = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+		if (entry.isDirectory()) files.push(...filesUnder(path.join(dir, entry.name), rel));
+		else files.push(rel);
+	}
+	return files;
+}
+function readManifest(manifestPath) {
+	let raw;
+	try {
+		raw = fs.readFileSync(manifestPath, "utf8");
+	} catch (cause) {
+		throw new Error(`Cannot read manifest at ${manifestPath}`, { cause });
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw new Error(`Cannot parse manifest at ${manifestPath} as JSON`, { cause });
+	}
+	if (!isRecord(parsed)) throw new Error(`Manifest at ${manifestPath} must be a JSON object`);
+	return parsed;
+}
+function expandManifestImport(root, key, rawValue, conditions) {
+	const value = typeof rawValue === "string" ? rawValue : resolveCondition(rawValue, conditions);
+	if (value === void 0) return {};
+	const pattern = parsePattern(key, value);
+	if (pattern === void 0) return { [key]: value };
+	return expandPattern(pattern, filesUnder(path.join(root, pattern.targetDirectory)));
+}
+function sortEntries(entries) {
+	return Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+}
+function rebaseScopePrefix(root, relativeTo, scope) {
+	const rebased = rebaseTarget(root, relativeTo, scope);
+	return scope.endsWith("/") && !rebased.endsWith("/") ? `${rebased}/` : rebased;
+}
+/**
+* Expand a package's exact and patterned `imports` into a Deno import map.
+*
+* Pattern targets are matched against files below {@link CreateImportMapOptions.root | root}.
+* Conditional targets use the configured condition order, and additional imports are applied last.
+*
+* @example Generate entries for the current project.
+* ```ts
+* import { createImportMap } from 'jsr:@kjanat/importmapify';
+*
+* const map = createImportMap({
+*   root: Deno.cwd(),
+*   conditions: ['deno', 'import', 'default'],
+* });
+*
+* console.log(map.imports['#lib/bytes']);
+* ```
+*
+* @param options Project, manifest, condition, and rebasing options.
+* @returns A sorted import map document.
+*/
+function createImportMap(options) {
+	const manifest = readManifest(path.join(options.root, options.manifest ?? "package.json"));
+	const manifestImports = isRecord(manifest.imports) ? manifest.imports : {};
+	const conditions = options.conditions !== void 0 && options.conditions.length > 0 ? options.conditions : DEFAULT_CONDITIONS;
+	const relativeTo = options.relativeTo ?? options.root;
+	const imports = {};
+	for (const [key, rawValue] of Object.entries(manifestImports)) {
+		const expanded = expandManifestImport(options.root, key, rawValue, conditions);
+		for (const [specifier, target] of Object.entries(expanded)) imports[specifier] = rebaseTarget(options.root, relativeTo, target);
+	}
+	for (const [key, value] of Object.entries(options.additionalImports ?? {})) imports[key] = rebaseTarget(options.root, relativeTo, value);
+	const scopes = {};
+	for (const [scope, mappings] of Object.entries(options.scopes ?? {})) {
+		const rebasedMappings = {};
+		for (const [key, value] of Object.entries(mappings)) rebasedMappings[key] = rebaseTarget(options.root, relativeTo, value);
+		scopes[rebaseScopePrefix(options.root, relativeTo, scope)] = sortEntries(rebasedMappings);
+	}
+	const sortedImports = sortEntries(imports);
+	const sortedScopes = Object.fromEntries(Object.entries(scopes).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+	return Object.keys(sortedScopes).length === 0 ? { imports: sortedImports } : {
+		imports: sortedImports,
+		scopes: sortedScopes
+	};
+}
+/**
+* Serialize an import map as stable, tab-indented JSON with a trailing newline.
+*
+* @example Format an import map for stdout.
+* ```ts
+* import { formatImportMap } from 'jsr:@kjanat/importmapify';
+*
+* const text = formatImportMap({
+*   imports: { '#config': './src/config.ts' },
+* });
+*
+* console.log(text);
+* ```
+*
+* @param map Import map to serialize.
+* @returns Formatted JSON ready to print or write.
+*/
+function formatImportMap(map) {
+	return `${JSON.stringify(map, null, "	")}\n`;
+}
+/**
+* Create an import map and write it to disk, creating parent directories as needed.
+*
+* Relative targets are automatically rebased from the project root to the output directory.
+*
+* @example Write the conventional Deno import map file.
+* ```ts
+* import { writeImportMap } from 'jsr:@kjanat/importmapify';
+*
+* const output = writeImportMap({
+*   root: Deno.cwd(),
+*   out: 'import_map.json',
+* });
+*
+* console.log(`Wrote ${output}`);
+* ```
+*
+* @param options Creation options plus the output path.
+* @returns The absolute path of the written file.
+*/
+function writeImportMap(options) {
+	const out = path.join(options.root, options.out);
+	const relativeTo = options.relativeTo ?? path.dirname(out);
+	const map = createImportMap({
+		...options,
+		relativeTo
+	});
+	fs.mkdirSync(path.dirname(out), { recursive: true });
+	fs.writeFileSync(out, formatImportMap(map));
+	return out;
+}
+//#endregion
+//#region src/cli.ts
+function parseKeyValue(raw) {
+	const eq = raw.indexOf("=");
+	if (eq === -1) throw new CLIError(`--import expects key=value, got "${raw}"`, {
+		code: "invalid-import-flag",
+		exitCode: 2
+	});
+	return [raw.slice(0, eq), raw.slice(eq + 1)];
+}
+function parseScope(raw) {
+	const separator = raw.indexOf("::");
+	const eq = raw.indexOf("=", separator + 2);
+	if (separator <= 0 || eq <= separator + 2 || eq === raw.length - 1) throw new CLIError(`--scope expects prefix::key=value, got "${raw}"`, {
+		code: "invalid-scope-flag",
+		exitCode: 2
+	});
+	return [
+		raw.slice(0, separator),
+		raw.slice(separator + 2, eq),
+		raw.slice(eq + 1)
+	];
+}
+/** DreamCLI command that writes, checks, or prints an expanded Deno import map. */
+const generateCommand = command("generate").description("Expand package.json subpath-pattern imports into a Deno import map.").flag("root", flag.path({
+	mustExist: true,
+	type: "directory"
+}).default(cwd()).describe("Project root containing the manifest.").alias("r")).flag("manifest", flag.string().default("package.json").describe("Manifest path, relative to root.").alias("m")).flag("out", flag.string().default("import_map.json").describe("Output path, relative to root.").alias("o")).flag("import", flag.array(flag.string()).describe("Additional import entry as key=value. Repeatable.").alias("i")).flag("scope", flag.array(flag.string()).describe("Scoped import as prefix::key=value. Repeatable.").alias("s")).flag("condition", flag.array(flag.string()).describe("Condition to try when a target is a conditional object. Repeatable.").alias("c")).flag("check", flag.boolean().describe("Exit 1 if the output file is stale instead of writing it.")).flag("stdout", flag.boolean().describe("Print the import map to stdout instead of writing it.")).example("importmapify --stdout", "Print the generated import map").example(`importmapify --import 'dreamcli=jsr:@kjanat/dreamcli@^3' --scope './tests/::dreamcli/testkit=jsr:@kjanat/dreamcli@^3/testkit'`, "Add global and test-scoped dependencies").example("importmapify --check", "Fail when the generated file is stale").action(({ flags, out }) => {
+	const { log, error, setExitCode } = out;
+	const { check, stdout, root, manifest, condition: cdts, out: of, import: imf, scope: scf } = flags;
+	if (check && stdout) throw new CLIError("--check and --stdout are mutually exclusive", {
+		code: "conflicting-flags",
+		exitCode: 2
+	});
+	const outPath = join(root, of);
+	const relativeTo = dirname(outPath);
+	const additionalImports = Object.fromEntries((imf ?? []).map(parseKeyValue));
+	const scopes = {};
+	for (const raw of scf ?? []) {
+		const [scope, key, value] = parseScope(raw);
+		const mappings = scopes[scope];
+		if (mappings === void 0) scopes[scope] = { [key]: value };
+		else mappings[key] = value;
+	}
+	const options = {
+		root,
+		manifest,
+		conditions: cdts,
+		additionalImports,
+		scopes,
+		relativeTo
+	};
+	if (stdout) {
+		log(formatImportMap(createImportMap(options)));
+		return;
+	}
+	if (check) {
+		const expected = formatImportMap(createImportMap(options));
+		if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : void 0) !== expected) {
+			error(`${outPath} is stale`);
+			setExitCode(1);
+			return;
+		}
+		log(`${outPath} is up to date`);
+		return;
+	}
+	log(`Wrote ${writeImportMap({
+		...options,
+		out: of
+	})}`);
+});
+//#endregion
+//#region src/mod.ts
+/**
+* Expand package import patterns into explicit Deno import map entries.
+*
+* Use the library API to create, format, or write deterministic import maps.
+* This module also runs the `importmapify` CLI when executed directly.
+*
+* @example Create an import map from the current package.
+* ```ts
+* import { createImportMap } from 'jsr:@kjanat/importmapify';
+*
+* const importMap = createImportMap({ root: Deno.cwd() });
+* console.log(importMap.imports);
+* ```
+*
+* @module importmapify
+*/
+const cli$1 = cli("importmapify").manifest({
+	from: import.meta.url,
+	files: ["package.json", "deno.json"]
+}).links().default(generateCommand).completions({ as: "flag" });
+if (import.meta.main) cli$1.run();
+//#endregion
+export { createImportMap, formatImportMap, writeImportMap };

package/import_map.json

@@ -0,0 +1,20 @@
+{
+	"imports": {
+		"#deno": "./deno.json",
+		"#pkg": "./package.json",
+		"#src/cli.ts": "./src/cli.ts",
+		"#src/expand.ts": "./src/expand.ts",
+		"#src/map.ts": "./src/map.ts",
+		"#src/mod.ts": "./src/mod.ts",
+		"@types/bun": "npm:bun-types@^1.3.14",
+		"bun": "npm:bun-types@^1.3.14",
+		"bun:test": "npm:bun-types@^1.3.14/test.d.ts",
+		"dreamcli": "jsr:@kjanat/dreamcli@^3.0.0-rc.11",
+		"dreamcli/": "jsr:@kjanat/dreamcli@^3.0.0-rc.11/"
+	},
+	"scopes": {
+		"./tests/": {
+			"dreamcli/testkit": "jsr:@kjanat/dreamcli@^3.0.0-rc.11/testkit"
+		}
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "0.1.0",
+	"version": "1.0.1",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",
@@ -12,7 +12,9 @@
 		"ansispeck"
 	],
 	"homepage": "https://github.com/kjanat/importmapify#readme",
-	"bugs": "https://github.com/kjanat/importmapify/issues",
+	"bugs": {
+		"url": "https://github.com/kjanat/importmapify/issues"
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/kjanat/importmapify.git"
@@ -26,48 +28,52 @@
 	"sideEffects": false,
 	"type": "module",
 	"imports": {
-		"#pkg": "./package.json"
+		"#pkg": "./package.json",
+		"#deno": "./deno.json",
+		"#src/*": "./src/*"
 	},
 	"exports": {
 		".": {
-			"types": "./dist/index.d.mts",
-			"default": "./dist/index.mjs"
+			"types": "./dist/mod.d.mts",
+			"default": "./dist/mod.mjs"
 		},
 		"./package.json": "./package.json"
 	},
-	"types": "./dist/index.d.mts",
 	"bin": {
-		"importmapify": "dist/importmapify.mjs"
+		"importmapify": "dist/mod.mjs"
 	},
-	"files": [
-		"dist"
-	],
+	"files": ["/dist", "/README.md", "/LICENSE", "/package.json", "/deno.json", "/import_map.json"],
 	"scripts": {
 		"bd": "tsdown",
 		"build": "tsdown",
 		"build:watch": "tsdown --watch",
 		"check": "biome check",
 		"check:fix": "biome check --fix",
-		"fmt": "dprint fmt",
+		"fmt": "biome check --fix 2>/dev/null; dprint fmt",
+		"jsr:publish": "bunx jsr publish --allow-dirty",
 		"lint": "biome lint",
-		"prepack": "bun --bun bd -l error",
+		"prepack": "bun --bun bd -l error && bun scripts/generate-importmap.ts",
 		"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",
+		"runbin": "node \"$(jq -r '.bin.[]' package.json)\"",
 		"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"
+		"typecheck": "bunx @typescript/native --noEmit",
+		"url:jsr": "printf 'url=https://jsr.io/%s@%s\n' \"$(jq -r '.name' deno.json)\" \"$(jq -r '.version' deno.json)\"",
+		"url:npm": "printf 'url=https://npm.im/package/%s/v/%s\n' \"$(jq -r '.name' package.json)\" \"$(jq -r '.version' package.json)\"",
+		"volta:bump": "volta pin node@latest npm@11; node --version>.node-version; bun bd"
 	},
 	"dependencies": {
-		"dreamcli": "npm:@kjanat/dreamcli@^3.0.0-rc.9"
+		"dreamcli": "npm:@kjanat/dreamcli@^3.0.0-rc.11"
 	},
 	"devDependencies": {
 		"@arethetypeswrong/core": "^0.18.5",
-		"@biomejs/biome": "2.5.2 || ^2.5.4",
 		"@types/bun": "^1.3.14",
+		"@types/deno": "^2.7.0",
 		"@types/node": "^26.1.1",
 		"@typescript/native": "npm:typescript@^7",
+		"biome": "npm:@biomejs/biome@^2.5.4",
 		"dprint": "^0.55.2",
 		"publint": "^0.3.21",
 		"sort-package-json": "^4.0.0",
@@ -78,7 +84,8 @@
 	"packageManager": "bun@1.3.14",
 	"engines": {
 		"bun": ">=1.3",
-		"node": ">=24"
+		"deno": ">=2",
+		"node": ">=22.22.2 <23 || >=24.2"
 	},
 	"volta": {
 		"node": "26.5.0",

package/dist/import-map.mjs

@@ -1 +0,0 @@
-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

@@ -1,2 +0,0 @@
-#!/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

@@ -1,19 +0,0 @@
-//#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

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