importmapify 1.0.1 → 1.1.0

package/README.md

@@ -29,22 +29,24 @@ npm install importmapify
 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                                     | `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                 |
+| 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 resolved against root; relative, absolute, or `file://` URL   | `import_map.json`   |
+| `--import key=value`        | `-i`  | Extra import entry; repeatable                                            | none                |
+| `--package name=target`     | `-p`  | Package expanded to a conformant bare and trailing-slash pair; 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` |
+| `--ext name`                | `-e`  | Restrict pattern matches to these file extensions; repeatable             | all files           |
+| `--check`                   |       | Exit 1 if the output file is stale, without writing it                    | off                 |
+| `--stdout`                  |       | Print the map instead of writing it                                       | off                 |
 
 Add global and test-scoped dependencies from the CLI:
 
 ```sh
 npx importmapify \
-  --import 'dreamcli=jsr:@kjanat/dreamcli@^3' \
+  --package 'dreamcli=jsr:@kjanat/dreamcli@^3' \
   --scope './tests/::dreamcli/testkit=jsr:@kjanat/dreamcli@^3/testkit'
 ```
 
@@ -69,11 +71,13 @@ const out = writeImportMap({
 });
 ```
 
-| 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. |
+| Export            | Signature                                                   | Purpose                                                                               |
+| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `defineConfig`    | `(options: WriteImportMapOptions) => WriteImportMapOptions` | Identity helper that types a config object for export and reuse.                      |
+| `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.                        |
+| `packageEntries`  | `(name: string, target: string) => Record<string, string>`  | Build the bare and trailing-slash entry pair a package needs to resolve its subpaths. |
 
 `CreateImportMapOptions`:
 
@@ -82,14 +86,78 @@ const out = writeImportMap({
 | `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                    |
+| `packages`          | Package specifiers mapped to targets, each expanded to a conformant bare and trailing-slash pair. | none                    |
+| `additionalImports` | Extra entries merged in after manifest expansion and packages; 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`                  |
+| `extensions`        | File extensions, with or without a leading dot, that pattern targets may match.                   | all files               |
 
-`WriteImportMapOptions` extends the above with `out`, the output path relative to `root`. `writeImportMap` rebases
+`WriteImportMapOptions` extends the above with an optional `out`, defaulting to `import_map.json` like the CLI. It is
+resolved against `root` and accepts a relative path, an absolute path, or a `file://` URL. `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.
 
+`defineConfig` returns its argument unchanged; it exists only to type an exported config object without a manual
+annotation. Under `isolatedDeclarations`, an exported binding still needs its own annotation, so there `defineConfig`
+helps only for a config used locally rather than exported.
+
+### Recipes
+
+Add dependencies with `packages`. Each entry expands to the bare specifier plus its conformant trailing-slash entry
+(`jsr:/` or `npm:/`), which Deno needs to resolve subpaths:
+
+```ts
+import { writeImportMap } from 'importmapify';
+
+writeImportMap({
+  root: import.meta.dirname,
+  packages: {
+    dreamcli: 'jsr:@kjanat/dreamcli@^3',
+    chalk: 'npm:chalk@5',
+  },
+});
+// dreamcli, dreamcli/ -> jsr:/@kjanat/dreamcli@^3/, chalk, chalk/ -> npm:/chalk@5/
+```
+
+Restrict pattern expansion to importable files with `extensions`, so a bare `./src/*` skips `.md`, `.json`, and other
+non-modules:
+
+```ts
+import { createImportMap } from 'importmapify';
+
+createImportMap({ root: import.meta.dirname, extensions: ['ts', 'tsx'] });
+```
+
+Build one conformant pair directly with `packageEntries`:
+
+```ts
+import { packageEntries } from 'importmapify';
+
+packageEntries('@std/async', 'jsr:@std/async@^1.0.0');
+// { '@std/async': 'jsr:@std/async@^1.0.0', '@std/async/': 'jsr:/@std/async@^1.0.0/' }
+```
+
+Type a reusable config with `defineConfig` and share it across calls:
+
+```ts
+import { createImportMap, defineConfig, writeImportMap } from 'importmapify';
+
+const config = defineConfig({ root: import.meta.dirname, packages: { chalk: 'npm:chalk@5' } });
+const map = createImportMap(config);
+const written = writeImportMap(config);
+```
+
+`root`, `relativeTo`, and `out` accept a path or a `file://` URL, so `import.meta.url` needs no `.pathname`:
+
+```ts
+import { writeImportMap } from 'importmapify';
+
+writeImportMap({
+  root: new URL('..', import.meta.url),
+  out: new URL('./import_map.json', import.meta.url),
+});
+```
+
 ### Project-local generator
 
 A checked-in wrapper keeps project-specific dependency and scope mappings in code:
@@ -102,7 +170,7 @@ import { writeImportMap } from 'importmapify';
 const output = writeImportMap({
   root: new URL('..', import.meta.url).pathname,
   out: 'import_map.json',
-  additionalImports: {
+  packages: {
     dreamcli: 'jsr:@kjanat/dreamcli@^3',
   },
   scopes: {
@@ -161,15 +229,13 @@ the generated map is:
   "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"
+    "#lib/codecs/hex": "./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`.
+Each matched file yields one specifier, the wildcard substituted into the key. A key with its own suffix, such as
+`#lib/*.js` targeting `./src/lib/*.ts`, produces the renamed specifier `#lib/bytes.js` pointing at `./src/lib/bytes.ts`.
 
 ## Scope and constraints
 
@@ -180,7 +246,9 @@ real filename: `#lib/bytes.js` and `#lib/bytes.ts`, both pointing at `./src/lib/
   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.
+- When two manifest entries produce the same key, the more specific one wins, matching Node's subpath resolution: an
+  exact key beats a pattern, and a longer prefix before `*` beats a shorter one. Declaration order does not matter.
+  `additionalImports` and `packages` still override manifest entries.
 - 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.
 

package/deno.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://raw.githubusercontent.com/denoland/deno/refs/heads/main/cli/schemas/config-file.v1.json",
 	"name": "@kjanat/importmapify",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [
@@ -21,7 +21,7 @@
 	"tasks": {
 		"build": {
 			"description": "build for npm distribution",
-			"command": "bunx tsdown",
+			"command": "bun run build",
 			"files": ["src/**", "package.json", "bun.lock"],
 			"output": ["dist/**", "deno.json"]
 		},
@@ -32,7 +32,7 @@
 		},
 		"importmapify": {
 			"description": "generate importmap for deno",
-			"command": "deno run --no-config -A scripts/generate-importmap.ts",
+			"command": "bun scripts/generate-importmap.ts",
 			"files": ["package.json", "scripts/generate-importmap.ts", "src/**"],
 			"output": ["import_map.json"]
 		}

package/dist/mod.d.mts

@@ -8,23 +8,30 @@ interface ImportMapDocument {
 }
 /** Options for creating an import map without writing it to disk. */
 interface CreateImportMapOptions {
-  /** Project directory containing the package manifest. */
-  readonly root: string;
+  /** Project directory containing the package manifest, as a path or `file://` URL. */
+  readonly root: string | URL;
   /** 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. */
+  /** Package specifiers mapped to targets, each expanded to a conformant bare and trailing-slash pair. */
+  readonly packages?: Readonly<Record<string, string>>;
+  /** Explicit entries merged after manifest imports and packages, 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;
+  /** Directory against which relative targets are rebased, as a path or `file://` URL. Defaults to {@link root}. */
+  readonly relativeTo?: string | URL;
+  /** File extensions, with or without a leading dot, that pattern targets may match. Unset matches every file. */
+  readonly extensions?: readonly string[];
 }
 /** Options for creating and writing an import map. */
 interface WriteImportMapOptions extends CreateImportMapOptions {
-  /** Output path relative to {@link CreateImportMapOptions.root | root}. */
-  readonly out: string;
+  /**
+   * Output path, resolved against {@link CreateImportMapOptions.root | root}. Accepts a relative path, an
+   * absolute path, a `file://` URL string, or a {@link URL}. Defaults to `import_map.json`.
+   */
+  readonly out?: string | URL;
 }
 /**
  * Expand a package's exact and patterned `imports` into a Deno import map.
@@ -32,8 +39,9 @@ interface WriteImportMapOptions extends CreateImportMapOptions {
  * 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.
+ * @example
  * ```ts
+ * // Generate entries for the current project.
  * import { createImportMap } from 'jsr:@kjanat/importmapify';
  *
  * const map = createImportMap({
@@ -51,8 +59,9 @@ declare function createImportMap(options: CreateImportMapOptions): ImportMapDocu
 /**
  * Serialize an import map as stable, tab-indented JSON with a trailing newline.
  *
- * @example Format an import map for stdout.
+ * @example
  * ```ts
+ * // Format an import map for stdout.
  * import { formatImportMap } from 'jsr:@kjanat/importmapify';
  *
  * const text = formatImportMap({
@@ -71,21 +80,58 @@ declare function formatImportMap(map: ImportMapDocument): string;
  *
  * Relative targets are automatically rebased from the project root to the output directory.
  *
- * @example Write the conventional Deno import map file.
+ * @example
  * ```ts
+ * // Write the conventional Deno import map file.
  * import { writeImportMap } from 'jsr:@kjanat/importmapify';
  *
- * const output = writeImportMap({
- *   root: Deno.cwd(),
- *   out: 'import_map.json',
- * });
+ * const output = writeImportMap({ root: Deno.cwd() });
  *
  * console.log(`Wrote ${output}`);
  * ```
  *
- * @param options Creation options plus the output path.
+ * @param options Creation options plus the optional output path.
  * @returns The absolute path of the written file.
  */
 declare function writeImportMap(options: WriteImportMapOptions): string;
+/**
+ * Build the two import map entries a package needs to resolve both itself and its subpaths.
+ *
+ * Deno's `importMap` resolution requires a trailing-slash entry for subpath imports, and a
+ * `jsr:` or `npm:` trailing-slash target only resolves in the `jsr:/` or `npm:/` form.
+ *
+ * @example
+ * ```ts
+ * import { packageEntries } from 'jsr:@kjanat/importmapify';
+ *
+ * packageEntries('@std/async', 'jsr:@std/async@^1.0.0');
+ * // { '@std/async': 'jsr:@std/async@^1.0.0', '@std/async/': 'jsr:/@std/async@^1.0.0/' }
+ * ```
+ *
+ * @param name Bare package specifier.
+ * @param target Exact target for {@link name}.
+ * @returns The bare entry and its trailing-slash subpath entry.
+ */
+declare function packageEntries(name: string, target: string): Record<string, string>;
+/**
+ * Type an import map configuration for export and reuse, then pass it to {@link createImportMap} or
+ * {@link writeImportMap}. Returns its input unchanged; it exists only for inference and autocomplete.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, writeImportMap } from 'jsr:@kjanat/importmapify';
+ *
+ * export const config = defineConfig({
+ *   root: import.meta.dirname,
+ *   packages: { dreamcli: 'jsr:@kjanat/dreamcli@^3' },
+ * });
+ *
+ * writeImportMap(config);
+ * ```
+ *
+ * @param options Import map configuration, with an optional `out`.
+ * @returns The same `options` value, typed as {@link WriteImportMapOptions}.
+ */
+declare function defineConfig(options: WriteImportMapOptions): WriteImportMapOptions;
 //#endregion
-export { type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, formatImportMap, writeImportMap };
+export { type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };

package/dist/mod.mjs

@@ -1,8 +1,9 @@
 #!/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 path, { dirname } from "node:path";
 import { cwd } from "node:process";
+import { fileURLToPath } from "node:url";
 //#region src/expand.ts
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -61,10 +62,7 @@ function expandPattern(pattern, files) {
 	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;
-		}
+		if (wildcard !== void 0) imports[`${pattern.keyPrefix}${wildcard}${pattern.keySuffix}`] = target;
 	}
 	return imports;
 }
@@ -120,6 +118,15 @@ function rebaseTarget(root, relativeTo, target) {
 //#endregion
 //#region src/map.ts
 const DEFAULT_CONDITIONS = ["import", "default"];
+const DEFAULT_OUT = "import_map.json";
+const SCHEME_PREFIX = /^(jsr|npm):(?!\/)/;
+function toPath(value) {
+	if (typeof value === "string") return value.startsWith("file://") ? fileURLToPath(value) : value;
+	return fileURLToPath(value.href);
+}
+function resolveOut(root, out) {
+	return path.resolve(toPath(root), toPath(out));
+}
 function filesUnder(dir, prefix = "") {
 	if (!fs.existsSync(dir)) return [];
 	const files = [];
@@ -146,12 +153,58 @@ function readManifest(manifestPath) {
 	if (!isRecord(parsed)) throw new Error(`Manifest at ${manifestPath} must be a JSON object`);
 	return parsed;
 }
-function expandManifestImport(root, key, rawValue, conditions) {
+function extensionFilter(extensions) {
+	const allowed = new Set(extensions.map((ext) => ext.startsWith(".") ? ext : `.${ext}`));
+	return (file) => allowed.has(path.extname(file));
+}
+function expandManifestImport(root, key, rawValue, { conditions, extensions }) {
 	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)));
+	const files = filesUnder(path.join(root, pattern.targetDirectory));
+	return expandPattern(pattern, extensions.length > 0 ? files.filter(extensionFilter(extensions)) : files);
+}
+function keyBaseLength(key) {
+	const star = key.indexOf("*");
+	return star === -1 ? key.length : star + 1;
+}
+/**
+* Order two manifest import keys by Node's subpath specificity: an exact key beats a pattern, a longer
+* prefix before `*` beats a shorter one, and a longer key breaks a remaining tie. Negative means `a` wins.
+*/
+function keySpecificity(a, b) {
+	const aExact = !a.includes("*");
+	if (aExact !== !b.includes("*")) return aExact ? -1 : 1;
+	const baseDelta = keyBaseLength(b) - keyBaseLength(a);
+	return baseDelta === 0 ? b.length - a.length : baseDelta;
+}
+function expandManifest(root, relativeTo, manifestImports, expansion) {
+	const imports = {};
+	const source = {};
+	for (const [key, rawValue] of Object.entries(manifestImports)) for (const [specifier, target] of Object.entries(expandManifestImport(root, key, rawValue, expansion))) {
+		const incumbent = source[specifier];
+		if (incumbent === void 0 || keySpecificity(key, incumbent) < 0) {
+			imports[specifier] = rebaseTarget(root, relativeTo, target);
+			source[specifier] = key;
+		}
+	}
+	return imports;
+}
+function collectAdditional(options) {
+	const entries = {};
+	for (const [name, target] of Object.entries(options.packages ?? {})) Object.assign(entries, packageEntries(name, target));
+	Object.assign(entries, options.additionalImports ?? {});
+	return entries;
+}
+function buildScopes$1(root, relativeTo, rawScopes) {
+	const scopes = {};
+	for (const [scope, mappings] of Object.entries(rawScopes)) {
+		const rebasedMappings = {};
+		for (const [key, value] of Object.entries(mappings)) rebasedMappings[key] = rebaseTarget(root, relativeTo, value);
+		scopes[rebaseScopePrefix(root, relativeTo, scope)] = sortEntries(rebasedMappings);
+	}
+	return scopes;
 }
 function sortEntries(entries) {
 	return Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
@@ -166,8 +219,9 @@ function rebaseScopePrefix(root, relativeTo, scope) {
 * 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.
+* @example
 * ```ts
+* // Generate entries for the current project.
 * import { createImportMap } from 'jsr:@kjanat/importmapify';
 *
 * const map = createImportMap({
@@ -182,22 +236,17 @@ function rebaseScopePrefix(root, relativeTo, scope) {
 * @returns A sorted import map document.
 */
 function createImportMap(options) {
-	const manifest = readManifest(path.join(options.root, options.manifest ?? "package.json"));
+	const root = toPath(options.root);
+	const manifest = readManifest(path.join(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 relativeTo = options.relativeTo === void 0 ? root : toPath(options.relativeTo);
+	const imports = expandManifest(root, relativeTo, manifestImports, {
+		conditions,
+		extensions: options.extensions ?? []
+	});
+	for (const [key, value] of Object.entries(collectAdditional(options))) imports[key] = rebaseTarget(root, relativeTo, value);
+	const scopes = buildScopes$1(root, relativeTo, options.scopes ?? {});
 	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 } : {
@@ -208,8 +257,9 @@ function createImportMap(options) {
 /**
 * Serialize an import map as stable, tab-indented JSON with a trailing newline.
 *
-* @example Format an import map for stdout.
+* @example
 * ```ts
+* // Format an import map for stdout.
 * import { formatImportMap } from 'jsr:@kjanat/importmapify';
 *
 * const text = formatImportMap({
@@ -230,23 +280,21 @@ function formatImportMap(map) {
 *
 * Relative targets are automatically rebased from the project root to the output directory.
 *
-* @example Write the conventional Deno import map file.
+* @example
 * ```ts
+* // Write the conventional Deno import map file.
 * import { writeImportMap } from 'jsr:@kjanat/importmapify';
 *
-* const output = writeImportMap({
-*   root: Deno.cwd(),
-*   out: 'import_map.json',
-* });
+* const output = writeImportMap({ root: Deno.cwd() });
 *
 * console.log(`Wrote ${output}`);
 * ```
 *
-* @param options Creation options plus the output path.
+* @param options Creation options plus the optional output path.
 * @returns The absolute path of the written file.
 */
 function writeImportMap(options) {
-	const out = path.join(options.root, options.out);
+	const out = resolveOut(options.root, options.out ?? "import_map.json");
 	const relativeTo = options.relativeTo ?? path.dirname(out);
 	const map = createImportMap({
 		...options,
@@ -256,12 +304,61 @@ function writeImportMap(options) {
 	fs.writeFileSync(out, formatImportMap(map));
 	return out;
 }
+function directoryTarget(target) {
+	return (target.endsWith("/") ? target : `${target}/`).replace(SCHEME_PREFIX, "$1:/");
+}
+/**
+* Build the two import map entries a package needs to resolve both itself and its subpaths.
+*
+* Deno's `importMap` resolution requires a trailing-slash entry for subpath imports, and a
+* `jsr:` or `npm:` trailing-slash target only resolves in the `jsr:/` or `npm:/` form.
+*
+* @example
+* ```ts
+* import { packageEntries } from 'jsr:@kjanat/importmapify';
+*
+* packageEntries('@std/async', 'jsr:@std/async@^1.0.0');
+* // { '@std/async': 'jsr:@std/async@^1.0.0', '@std/async/': 'jsr:/@std/async@^1.0.0/' }
+* ```
+*
+* @param name Bare package specifier.
+* @param target Exact target for {@link name}.
+* @returns The bare entry and its trailing-slash subpath entry.
+*/
+function packageEntries(name, target) {
+	return {
+		[name]: target,
+		[`${name}/`]: directoryTarget(target)
+	};
+}
+/**
+* Type an import map configuration for export and reuse, then pass it to {@link createImportMap} or
+* {@link writeImportMap}. Returns its input unchanged; it exists only for inference and autocomplete.
+*
+* @example
+* ```ts
+* import { defineConfig, writeImportMap } from 'jsr:@kjanat/importmapify';
+*
+* export const config = defineConfig({
+*   root: import.meta.dirname,
+*   packages: { dreamcli: 'jsr:@kjanat/dreamcli@^3' },
+* });
+*
+* writeImportMap(config);
+* ```
+*
+* @param options Import map configuration, with an optional `out`.
+* @returns The same `options` value, typed as {@link WriteImportMapOptions}.
+*/
+function defineConfig(options) {
+	return options;
+}
 //#endregion
 //#region src/cli.ts
-function parseKeyValue(raw) {
+function parseKeyValue(raw, flagName, code) {
 	const eq = raw.indexOf("=");
-	if (eq === -1) throw new CLIError(`--import expects key=value, got "${raw}"`, {
-		code: "invalid-import-flag",
+	if (eq === -1) throw new CLIError(`--${flagName} expects key=value, got "${raw}"`, {
+		code,
 		exitCode: 2
 	});
 	return [raw.slice(0, eq), raw.slice(eq + 1)];
@@ -279,34 +376,46 @@ function parseScope(raw) {
 		raw.slice(eq + 1)
 	];
 }
+function parseEntries(raws, flagName, code) {
+	const entries = {};
+	for (const raw of raws) {
+		const [key, value] = parseKeyValue(raw, flagName, code);
+		entries[key] = value;
+	}
+	return entries;
+}
+function buildScopes(raws) {
+	const scopes = {};
+	for (const raw of raws) {
+		const [scope, key, value] = parseScope(raw);
+		const mappings = scopes[scope];
+		if (mappings === void 0) scopes[scope] = { [key]: value };
+		else mappings[key] = value;
+	}
+	return scopes;
+}
 /** 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 }) => {
+}).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(DEFAULT_OUT).describe("Output path resolved against root; relative, absolute, or file:// URL.").alias("o")).flag("import", flag.array(flag.string()).describe("Additional import entry as key=value. Repeatable.").alias("i")).flag("package", flag.array(flag.string()).describe("Package as name=target, expanded to a conformant bare and trailing-slash pair. Repeatable.").alias("p")).flag("ext", flag.array(flag.string()).describe("Restrict pattern matches to these file extensions. Repeatable.").alias("e")).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 --package '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;
+	const { check, stdout, root, manifest, condition: cdts, out: of, import: imf, package: pkf, ext: exf, 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 outPath = resolveOut(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
+		packages: parseEntries(pkf ?? [], "package", "invalid-package-flag"),
+		additionalImports: parseEntries(imf ?? [], "import", "invalid-import-flag"),
+		scopes: buildScopes(scf ?? []),
+		relativeTo,
+		extensions: exf
 	};
 	if (stdout) {
 		log(formatImportMap(createImportMap(options)));
@@ -335,8 +444,9 @@ const generateCommand = command("generate").description("Expand package.json sub
 * 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.
+* @example
 * ```ts
+* // Create an import map from the current package.
 * import { createImportMap } from 'jsr:@kjanat/importmapify';
 *
 * const importMap = createImportMap({ root: Deno.cwd() });
@@ -351,4 +461,4 @@ const cli$1 = cli("importmapify").manifest({
 }).links().default(generateCommand).completions({ as: "flag" });
 if (import.meta.main) cli$1.run();
 //#endregion
-export { createImportMap, formatImportMap, writeImportMap };
+export { createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };

package/import_map.json

@@ -2,19 +2,25 @@
 	"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/"
+		"#src/cli": "./src/cli.ts",
+		"#src/expand": "./src/expand.ts",
+		"#src/map": "./src/map.ts",
+		"#src/mod": "./src/mod.ts",
+		"@types/bun": "npm:@types/bun@1.3.14",
+		"ansispeck": "jsr:@kjanat/ansispeck@0.2.0",
+		"ansispeck/": "jsr:/@kjanat/ansispeck@0.2.0/",
+		"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/",
+		"sort-package-json": "npm:sort-package-json@4.0.0",
+		"sort-package-json/": "npm:/sort-package-json@4.0.0/",
+		"tsdown": "npm:tsdown@0.22.8",
+		"tsdown/": "npm:/tsdown@0.22.8/"
 	},
 	"scopes": {
 		"./tests/": {
-			"dreamcli/testkit": "jsr:@kjanat/dreamcli@^3.0.0-rc.11/testkit"
+			"dreamcli/testkit": "jsr:@kjanat/dreamcli@3.0.0-rc.11/testkit"
 		}
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",
@@ -30,7 +30,7 @@
 	"imports": {
 		"#pkg": "./package.json",
 		"#deno": "./deno.json",
-		"#src/*": "./src/*"
+		"#src/*": "./src/*.ts"
 	},
 	"exports": {
 		".": {
@@ -52,17 +52,17 @@
 		"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 && 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)\"",
-		"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",
+		"prepack": "run -q build -l error",
+		"prepare": "./scripts/generate-importmap.ts",
+		"runbin": "node \"$(jq -r '.bin.importmapify' package.json)\"",
+		"test": "bun test",
+		"test:coverage": "run -q test --coverage",
+		"test:smoke": "./scripts/smoke.mjs",
+		"test:watch": "run -q test --watch",
+		"typecheck": "run @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"
+		"volta:bump": "volta pin node@latest npm@11; node --version>.node-version; run bd"
 	},
 	"dependencies": {
 		"dreamcli": "npm:@kjanat/dreamcli@^3.0.0-rc.11"
@@ -76,7 +76,9 @@
 		"biome": "npm:@biomejs/biome@^2.5.4",
 		"dprint": "^0.55.2",
 		"publint": "^0.3.21",
+		"runner-run": "^0.20.0",
 		"sort-package-json": "^4.0.0",
+		"tombi": "^1.2.1",
 		"tsdown": "^0.22.7",
 		"typescript": ">=6,<7",
 		"unplugin-unused": "^0.5.7"