importmapify 1.4.0 → 1.6.0

package/README.md

@@ -21,12 +21,14 @@ per matched source file instead. This package performs that expansion and writes
 
 ```sh
 npm install importmapify
+deno add jsr:@kjanat/importmapify
 ```
 
 ## CLI
 
 ```sh
 npx importmapify --root . --out import_map.json
+deno run -A jsr:@kjanat/importmapify [...]
 ```
 
 | Flag                        | Alias | Meaning                                                                   | Default             |
@@ -39,6 +41,8 @@ npx importmapify --root . --out import_map.json
 | `--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           |
+| `--filter regex`            | `-f`  | Regular expression a pattern target path must match; repeatable           | all files           |
+| `--indent value`            |       | Indentation as a number of spaces or the word `tab`                       | tab                 |
 | `--config path`             | `-C`  | Config file path; skips discovery                                         | auto-discovered     |
 | `--no-config`               |       | Skip config file discovery                                                | off                 |
 | `--check`                   |       | Exit 1 if the output file is stale, without writing it                    | off                 |
@@ -84,9 +88,9 @@ Then `npx importmapify` reads it automatically. Point at a specific file with `-
 `--no-config`.
 
 Explicitly-passed flags override the config, which overrides built-in defaults: `--import`/`--package`/`--scope` merge
-onto the config's records with flag keys winning; `--condition`/`--ext` replace; `--root`/`--manifest`/`--out` win when
-passed. Configs are imported natively; a TypeScript config needs a type-stripping runtime (Bun, Deno, or Node \>= 22.6);
-on older Node use a `.mjs`/`.cjs`/`.js` config.
+onto the config's records with flag keys winning; `--condition`/`--ext`/`--filter` replace;
+`--root`/`--manifest`/`--out` win when passed. Configs are imported natively; a TypeScript config needs a type-stripping
+runtime (Bun, Deno, or Node \>= 22.6); on older Node use a `.mjs`/`.cjs`/`.js` config.
 
 ## Library
 
@@ -126,15 +130,17 @@ const out = writeImportMap({
 | `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               |
+| `extensions`        | Extension whitelist limiting which pattern targets are kept.                                      | all files               |
+| `filter`            | `RegExp`/predicate matchers a pattern target path must pass; combines with `extensions`.          | all files               |
 
-`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.
+`WriteImportMapOptions` extends the above with an optional `out`, defaulting to `import_map.json` like the CLI, and an
+optional `indent` with `JSON.stringify` space semantics (a number of spaces or a literal string), defaulting to a tab.
+`out` 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.
 
-`Config` extends `Partial<WriteImportMapOptions>` with an optional `hooks` field — the shape a config file's default
-export and `defineConfig` take, with every field optional. An omitted `root` defaults to the config file's own
+`Config` extends `Partial<WriteImportMapOptions>` with an optional `hooks` field. It is the shape a config file's
+default export and `defineConfig` take, with every field optional. An omitted `root` defaults to the config file's own
 directory; the CLI supplies the remaining defaults.
 
 `defineConfig` returns its argument unchanged; it exists only to type a config object for export and reuse without a
@@ -172,6 +178,17 @@ import { createImportMap } from 'importmapify';
 createImportMap({ root: import.meta.dirname, extensions: ['ts', 'tsx'] });
 ```
 
+`filter` takes `RegExp` or predicate matchers tested against each candidate target path; a target is kept only when
+every matcher accepts it. Combined with `extensions`, this drops hashed build chunks a `dist/*` pattern would otherwise
+enumerate:
+
+```ts
+import { createImportMap } from 'importmapify';
+
+// Keep .js targets whose path is not an internal chunk like ./dist/internal-qo9O8jzH.js.
+createImportMap({ root: import.meta.dirname, extensions: ['js'], filter: [/^(?!.*internal)/] });
+```
+
 Build one conformant pair directly with `packageEntries`:
 
 ```ts

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.4.0",
+	"version": "1.6.0",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [
@@ -16,26 +16,38 @@
 	"compilerOptions": {
 		"lib": ["ESNext", "DOM", "deno.ns"]
 	},
-	"importMap": "./import_map.json",
+	"importMap": "import_map.json",
 	"license": "MIT",
 	"tasks": {
 		"build": {
-			"description": "build for npm distribution",
-			"command": "bun run build",
-			"files": ["src/**", "package.json", "bun.lock"],
-			"output": ["dist/**", "deno.json"]
+			"description": "build for npm distribution (requires bun)",
+			"command": "bun run build"
 		},
 		"publish": {
 			"command": "deno publish --config deno.json --allow-dirty",
-			"description": "Publish package to jsr",
-			"dependencies": ["importmapify"]
+			"description": "Publish package to jsr"
 		},
 		"importmapify": {
-			"description": "generate importmap for deno",
-			"command": "bun scripts/generate-importmap.ts",
-			"files": ["package.json", "scripts/generate-importmap.ts", "src/**"],
-			"output": ["import_map.json"]
-		}
+			"description": "generate importmap for deno (requires bun)",
+			"command": "bun scripts/generate-importmap.ts"
+		},
+		"doc:html": {
+			"command": "sh -c 'set -e; root=$PWD; [ -f dist/mod.d.mts ] || bun run build; tmp=$(mktemp -d); { awk \"NR>1{print} /\\*\\//{if(NR>1) exit}\" src/mod.ts; cat dist/mod.d.mts; } > \"$tmp/importmapify.d.ts\"; cd \"$tmp\"; deno doc --html --name=\"$(jq -r .name \"$root/package.json\")\" --category-docs=\"$root/category-docs.json\" --output=\"$root/.denodocs/\" ./importmapify.d.ts; cd \"$root\"; deno doc --json $(jq -r \".exports | .[]? // .\" deno.json) > \"$tmp/nodes.json\" 2>/dev/null; bun scripts/link-source-buttons.mjs .denodocs \"$tmp/nodes.json\" \"$(git rev-parse HEAD)\"; bun scripts/inject-favicon.mjs .denodocs assets/favicon.svg; bunx vite-svg-to-ico generate assets/favicon.svg --out-dir .denodocs; rm -rf \"$tmp\"'",
+			"description": "generate categorized HTML docs into .denodocs (requires bun)"
+		},
+		"doc:json": {
+			"command": "mkdir -p .denodocs && deno doc --name=\"$(jq -r .name package.json)\" --json $(jq -r '.exports | .[]? // .' deno.json) > .denodocs/documentation.json",
+			"description": "emit JSON doc nodes into .denodocs"
+		},
+		"doc:lint": {
+			"command": "deno doc --lint $(jq -r '.exports | .[]? // .' deno.json)",
+			"description": "lint docs on exported symbols"
+		},
+		"format:docs": {
+			"command": "bunx dprint fmt --includes-override '.denodocs/**/*.{html,css,js,json}' --excludes-override='!.denodocs/**/*.{html,css,js,json}' --no-gitignore --allow-no-files",
+			"description": "format the output docs (requires bun)"
+		},
+		"ci:docs": "run -s doc:html doc:json format:docs"
 	},
 	"lint": {
 		"rules": {
@@ -43,7 +55,7 @@
 		}
 	},
 	"preferPackageJson": false,
-	"homepage": "https://github.com/kjanat/importmapify#readme",
+	"homepage": "https://importmapify.kjanat.dev",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/kjanat/importmapify.git"

package/dist/mod.d.mts

@@ -1,67 +1,335 @@
-//#region src/map.d.ts
-/** A deterministic Deno import map generated from package import entries. */
+//#region src/types.d.ts
+/**
+ * A deterministic Deno import map generated from package import entries, following the
+ * {@link https://html.spec.whatwg.org/multipage/webappapis.html#import-maps | Import Maps Standard}.
+ *
+ * @example
+ * ```ts
+ * import type { ImportMapDocument } from 'jsr:@kjanat/importmapify';
+ *
+ * const doc: ImportMapDocument = {
+ *   imports: { '#lib/bytes': './src/lib/bytes.ts' },
+ *   scopes: { './tests/': { '#lib/bytes': './tests/stub/bytes.ts' } },
+ * };
+ * ```
+ * @category Generate
+ */
 interface ImportMapDocument {
-  /** Exact specifier-to-target mappings, sorted by specifier. */
+  /**
+   * Exact specifier-to-target mappings, sorted by specifier, as in Deno's
+   * {@link https://docs.deno.com/runtime/reference/deno_json/#custom-path-mappings | custom path mappings}.
+   *
+   * @example
+   * ```ts
+   * const imports = { '#lib/bytes': './src/lib/bytes.ts' };
+   * ```
+   */
   readonly imports: Readonly<Record<string, string>>;
-  /** Scope prefixes mapped to sorted, scope-specific import overrides. */
+  /**
+   * Scope prefixes mapped to sorted, scope-specific import overrides, as in Deno's
+   * {@link https://docs.deno.com/runtime/reference/deno_json/#scoped-mappings | scoped mappings}.
+   *
+   * @example
+   * ```ts
+   * const scopes = { './tests/': { '#lib/bytes': './tests/stub/bytes.ts' } };
+   * ```
+   */
   readonly scopes?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 }
-/** Options for creating an import map without writing it to disk. */
+/**
+ * A filesystem location as a path string or `file://` URL, accepted wherever an option names a
+ * directory or file.
+ *
+ * @example
+ * ```ts
+ * import type { PathOrUrl } from 'jsr:@kjanat/importmapify';
+ *
+ * const root: PathOrUrl = new URL('..', import.meta.url);
+ * ```
+ * @category Options
+ */
+type PathOrUrl = string | URL;
+/**
+ * A matcher for {@link CreateImportMapOptions.filter | filter}, tested against a candidate target
+ * path such as `./dist/internal-qo9O8jzH.js`. A target is kept only when every matcher accepts it.
+ *
+ * @example
+ * ```ts
+ * import type { TargetFilter } from 'jsr:@kjanat/importmapify';
+ *
+ * // Drop hashed internal chunks like ./dist/internal-qo9O8jzH.js.
+ * const filter: readonly TargetFilter[] = [/^(?!.*internal)/];
+ * ```
+ * @category Options
+ */
+type TargetFilter = RegExp | ((target: string) => boolean);
+/**
+ * Options for creating an import map without writing it to disk.
+ *
+ * @example
+ * ```ts
+ * import { createImportMap, type CreateImportMapOptions } from 'jsr:@kjanat/importmapify';
+ *
+ * const options: CreateImportMapOptions = {
+ *   root: import.meta.dirname,
+ *   conditions: ['deno', 'import', 'default'],
+ *   extensions: ['ts', 'tsx'],
+ * };
+ *
+ * createImportMap(options);
+ * ```
+ * @category Options
+ */
 interface CreateImportMapOptions {
-  /** 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`. */
+  /**
+   * Project directory containing the package {@linkcode manifest}, as a path or `file://` URL.
+   *
+   * @example
+   * ```ts
+   * const root = import.meta.dirname;
+   * ```
+   */
+  readonly root: PathOrUrl;
+  /**
+   * Manifest path relative to {@link root}. Defaults to `package.json`.
+   *
+   * @example
+   * ```ts
+   * const manifest = 'deno.json';
+   * ```
+   * @defaultValue `'package.json'`
+   */
   readonly manifest?: string;
-  /** Conditional import keys to try in order. Defaults to `import`, then `default`. */
+  /**
+   * Conditional import keys to try in order. Defaults to `import`, then `default`.
+   *
+   * @example
+   * ```ts
+   * const conditions = ['deno', 'import', 'default'];
+   * ```
+   * @defaultValue `['import', 'default']`
+   */
   readonly conditions?: readonly string[];
-  /** Package specifiers mapped to targets, each expanded to a conformant bare and trailing-slash pair. */
+  /**
+   * Package specifiers mapped to targets, each expanded to a conformant bare and trailing-slash pair.
+   * Defaults to none.
+   *
+   * @example
+   * ```ts
+   * const packages = { dreamcli: 'jsr:@kjanat/dreamcli@^3' };
+   * ```
+   * @defaultValue `{}`
+   */
   readonly packages?: Readonly<Record<string, string>>;
-  /** Explicit entries merged after manifest imports and packages, overriding duplicate keys. */
+  /**
+   * Explicit entries merged after manifest imports and packages, overriding duplicate keys. Defaults to none.
+   *
+   * @example
+   * ```ts
+   * const additionalImports = { '#config': './src/config.ts' };
+   * ```
+   * @defaultValue `{}`
+   */
   readonly additionalImports?: Readonly<Record<string, string>>;
-  /** Scope-specific import overrides keyed by scope prefix. */
+  /**
+   * Scope-specific import overrides keyed by scope prefix, following Deno's
+   * {@link https://docs.deno.com/runtime/reference/deno_json/#scoped-mappings | scoped mappings}. Defaults to none.
+   *
+   * @example
+   * ```ts
+   * const scopes = { './tests/': { '#lib/bytes': './tests/stub/bytes.ts' } };
+   * ```
+   * @defaultValue `{}`
+   */
   readonly scopes?: Readonly<Record<string, Readonly<Record<string, 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. */
+  /**
+   * Directory the generated import map will be read from, as a path or `file://` URL.
+   *
+   * Manifest targets are written relative to {@link root}, but Deno resolves an import map's relative targets
+   * from the location of the map file. Each relative target is rewritten to be relative to this directory
+   * instead, so it still points at the right file once the map moves. `writeImportMap` and the CLI set
+   * this automatically to the output file's directory; set it yourself only when placing an in-memory map
+   * somewhere other than {@link root}. Defaults to {@link root}.
+   *
+   * @example
+   * ```ts
+   * // Map root is /proj, target is ./src/bytes.ts, map will live in /proj/.cache.
+   * const relativeTo = '/proj/.cache';
+   * // The emitted target becomes ../src/bytes.ts, which resolves back to /proj/src/bytes.ts.
+   * ```
+   * @defaultValue {@link root}
+   */
+  readonly relativeTo?: PathOrUrl;
+  /**
+   * Extension whitelist limiting which pattern targets are kept, with or without leading dots.
+   * Combines with {@link filter}. Unset keeps every extension.
+   *
+   * @example
+   * ```ts
+   * const extensions = ['ts', 'tsx'];
+   * ```
+   * @defaultValue `[]`
+   */
   readonly extensions?: readonly string[];
+  /**
+   * Matchers a candidate pattern target must pass, each tested against the target path. A target is kept
+   * only when every matcher accepts it. Combines with {@link extensions}. Unset keeps every target.
+   *
+   * @example
+   * ```ts
+   * // Keep .js targets that are not hashed internal chunks.
+   * const options = { extensions: ['js'], filter: [/^(?!.*internal)/] };
+   * ```
+   * @defaultValue `[]`
+   */
+  readonly filter?: readonly TargetFilter[];
 }
-/** Options for creating and writing an import map. */
+/**
+ * Options for creating and writing an import map.
+ *
+ * @example
+ * ```ts
+ * import { writeImportMap, type WriteImportMapOptions } from 'jsr:@kjanat/importmapify';
+ *
+ * const options: WriteImportMapOptions = {
+ *   root: import.meta.dirname,
+ *   out: '.cache/maps/import_map.json',
+ * };
+ *
+ * writeImportMap(options);
+ * ```
+ * @category Options
+ */
 interface WriteImportMapOptions extends CreateImportMapOptions {
   /**
    * 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`.
+   *
+   * Deno loads the written file through the `importMap` field in `deno.json` or the `--import-map` flag; see
+   * {@link https://docs.deno.com/runtime/fundamentals/modules/#differentiating-between-imports-or-importmap-in-deno.json-and---import-map-option | Deno: imports vs importMap}.
+   *
+   * @example
+   * ```ts
+   * const out = '.cache/maps/import_map.json';
+   * ```
+   * @defaultValue `'import_map.json'`
+   */
+  readonly out?: PathOrUrl;
+  /**
+   * Indentation for the serialized map, with the semantics of `JSON.stringify`'s
+   * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#space | space parameter}:
+   * a number of spaces per level or a literal indent string. Defaults to a tab.
+   *
+   * @example
+   * ```ts
+   * const indent = 2;
+   * ```
+   * @defaultValue `'\t'`
    */
-  readonly out?: string | URL;
+  readonly indent?: string | number;
 }
-/** Resolved paths shared by every generation hook. */
+/**
+ * Resolved paths shared by every generation hook.
+ *
+ * @example
+ * ```ts
+ * import type { HookContext } from 'jsr:@kjanat/importmapify';
+ *
+ * const logRoot = (ctx: HookContext) => console.log(`scanning ${ctx.root}, writing ${ctx.out}`);
+ * ```
+ * @category Configuration
+ */
 interface HookContext {
-  /** Absolute project root that gets scanned. */
+  /**
+   * Absolute project root that gets scanned.
+   *
+   * @example
+   * ```ts
+   * const root = '/home/me/project';
+   * ```
+   */
   readonly root: string;
-  /** Absolute output path the map resolves against. */
+  /**
+   * Absolute output path the map resolves against.
+   *
+   * @example
+   * ```ts
+   * const out = '/home/me/project/import_map.json';
+   * ```
+   */
   readonly out: string;
 }
 /**
  * Lifecycle hooks the CLI runs around import map generation, modeled on tsdown's hooks.
  *
  * Each hook may be async; the CLI awaits it. The synchronous library functions ignore hooks.
+ *
+ * @example
+ * ```ts
+ * // Build generated targets before the scan so they land in the map.
+ * import { execSync } from 'node:child_process';
+ * import { defineConfig } from 'jsr:@kjanat/importmapify';
+ *
+ * export default defineConfig({
+ *   hooks: {
+ *     'generate:before': () => execSync('deno task build', { stdio: 'inherit' }),
+ *   },
+ * });
+ * ```
+ * @category Configuration
  */
 interface ImportMapHooks {
-  /** Runs before the filesystem is scanned. Build pattern targets here so they exist when patterns expand. */
+  /**
+   * Runs before the filesystem is scanned. Build pattern targets here so they exist when patterns expand.
+   *
+   * @example
+   * ```ts
+   * const onBefore = (ctx) => console.log('building targets under', ctx.root);
+   * ```
+   */
   readonly "generate:before": (context: HookContext) => void | Promise<void>;
-  /** Runs after the map is generated and emitted. */
+  /**
+   * Runs after the map is generated and emitted.
+   *
+   * @example
+   * ```ts
+   * const onDone = (ctx) => console.log('mapped', Object.keys(ctx.map.imports).length, 'imports');
+   * ```
+   */
   readonly "generate:done": (context: HookContext & {
     readonly map: ImportMapDocument;
   }) => void | Promise<void>;
 }
 /**
- * An importmapify config file: the shape a config file's default export and {@linkcode defineConfig} take.
+ * An importmapify config file: the shape a config file's default export and `defineConfig` take.
  * Every field is optional; the config loader and CLI supply {@linkcode CreateImportMapOptions.root | root}
  * and the remaining defaults.
+ *
+ * @example
+ * ```ts
+ * // importmapify.config.ts; root is omitted, so it defaults to this file's directory.
+ * import { defineConfig } from 'jsr:@kjanat/importmapify';
+ *
+ * export default defineConfig({
+ *   packages: { dreamcli: 'jsr:@kjanat/dreamcli@^3' },
+ *   extensions: ['ts'],
+ * });
+ * ```
+ * @category Configuration
  */
 interface Config extends Partial<WriteImportMapOptions> {
-  /** Lifecycle hooks the CLI runs around generation. Ignored by {@link writeImportMap} and {@link createImportMap}. */
+  /**
+   * Lifecycle hooks the CLI runs around generation. Ignored by `writeImportMap` and `createImportMap`.
+   *
+   * @example
+   * ```ts
+   * const hooks = { 'generate:before': (ctx) => console.log(ctx.root) };
+   * ```
+   */
   readonly hooks?: Partial<ImportMapHooks>;
 }
+//#endregion
+//#region src/map.d.ts
 /**
  * Expand a package's exact and patterned `imports` into a Deno import map.
  *
@@ -83,27 +351,28 @@ interface Config extends Partial<WriteImportMapOptions> {
  *
  * @param options Project, manifest, condition, and rebasing options.
  * @returns A sorted import map document.
+ * @category Generate
  */
 declare function createImportMap(options: CreateImportMapOptions): ImportMapDocument;
 /**
- * Serialize an import map as stable, tab-indented JSON with a trailing newline.
+ * Serialize an import map as stable JSON with a trailing newline.
  *
  * @example
  * ```ts
- * // Format an import map for stdout.
+ * // Format an import map for stdout, indented with two spaces.
  * import { formatImportMap } from 'jsr:@kjanat/importmapify';
  *
- * const text = formatImportMap({
- *   imports: { '#config': './src/config.ts' },
- * });
+ * const text = formatImportMap({ imports: { '#config': './src/config.ts' } }, 2);
  *
  * console.log(text);
  * ```
  *
  * @param map Import map to serialize.
+ * @param indent Indentation with `JSON.stringify` space semantics; defaults to a tab.
  * @returns Formatted JSON ready to print or write.
+ * @category Generate
  */
-declare function formatImportMap(map: ImportMapDocument): string;
+declare function formatImportMap(map: ImportMapDocument, indent?: string | number): string;
 /**
  * Create an import map and write it to disk, creating parent directories as needed.
  *
@@ -121,6 +390,7 @@ declare function formatImportMap(map: ImportMapDocument): string;
  *
  * @param options Creation options plus the optional output path.
  * @returns The absolute path of the written file.
+ * @category Generate
  */
 declare function writeImportMap(options: WriteImportMapOptions): string;
 /**
@@ -140,6 +410,7 @@ declare function writeImportMap(options: WriteImportMapOptions): string;
  * @param name Bare package specifier.
  * @param target Exact target for {@link name}.
  * @returns The bare entry and its trailing-slash subpath entry.
+ * @category Generate
  */
 declare function packageEntries(name: string, target: string): Record<string, string>;
 /**
@@ -158,10 +429,24 @@ declare function packageEntries(name: string, target: string): Record<string, st
  * writeImportMap(config);
  * ```
  *
+ * @example
+ * ```ts
+ * // Config file with a build hook: generate:before runs before the CLI scans.
+ * import { execSync } from 'node:child_process';
+ * import { defineConfig } from 'jsr:@kjanat/importmapify';
+ *
+ * export default defineConfig({
+ *   hooks: {
+ *     'generate:before': () => execSync('deno task build', { stdio: 'inherit' }),
+ *   },
+ * });
+ * ```
+ *
  * @param config Import map configuration; every field is optional.
- * @returns The same `config` value with its exact type preserved, so a config that includes `root` stays
+ * @returns The same {@linkcode config} value with its exact type preserved, so a config that includes {@linkcode CreateImportMapOptions.root} stays
  * assignable to {@link writeImportMap} while one that omits it is still a valid config file.
+ * @category Configuration
  */
 declare function defineConfig<T extends Config>(config: T): T;
 //#endregion
-export { type Config, type CreateImportMapOptions, type HookContext, type ImportMapDocument, type ImportMapHooks, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };
+export { type Config, type CreateImportMapOptions, type HookContext, type ImportMapDocument, type ImportMapHooks, type PathOrUrl, type TargetFilter, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };

package/dist/mod.mjs

@@ -118,6 +118,10 @@ function rebaseTarget(root, relativeTo, target) {
 }
 //#endregion
 //#region src/config.ts
+/** Set `key` on `target` unless the value is `undefined`, keeping the key/value pairing type-checked. */
+function assign(target, key, value) {
+	if (value !== void 0) target[key] = value;
+}
 const CONFIG_BASENAMES = ["importmapify.config", ".importmapify"];
 const CONFIG_EXTENSIONS = [
 	"mjs",
@@ -169,9 +173,18 @@ function asString(value) {
 function asPath(value) {
 	return typeof value === "string" || value instanceof URL ? value : void 0;
 }
+function asIndent(value) {
+	return typeof value === "string" || typeof value === "number" ? value : void 0;
+}
 function asStringArray(value) {
 	return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
 }
+function isTargetFilter(value) {
+	return value instanceof RegExp || typeof value === "function";
+}
+function asTargetFilters(value) {
+	return Array.isArray(value) && value.every(isTargetFilter) ? value : void 0;
+}
 function asStringRecord(value) {
 	if (!isRecord(value)) return;
 	const record = {};
@@ -191,6 +204,11 @@ function asScopes(value) {
 	}
 	return scopes;
 }
+function resolveRoot(root, configDir) {
+	if (root === void 0) return configDir;
+	if (typeof root === "string" && !path.isAbsolute(root) && !root.startsWith("file://")) return path.resolve(configDir, root);
+	return root;
+}
 function isHook(value) {
 	return typeof value === "function";
 }
@@ -214,29 +232,18 @@ function asHooks(value) {
 * @returns The subset of {@link WriteImportMapOptions} the config declares, plus any hooks.
 */
 function configToOptions(config, configDir) {
-	const result = {};
-	const root = asPath(config.root);
-	if (root === void 0) result.root = configDir;
-	else if (typeof root === "string" && !path.isAbsolute(root) && !root.startsWith("file://")) result.root = path.resolve(configDir, root);
-	else result.root = root;
-	const manifest = asString(config.manifest);
-	if (manifest !== void 0) result.manifest = manifest;
-	const out = asPath(config.out);
-	if (out !== void 0) result.out = out;
-	const relativeTo = asPath(config.relativeTo);
-	if (relativeTo !== void 0) result.relativeTo = relativeTo;
-	const conditions = asStringArray(config.conditions);
-	if (conditions !== void 0) result.conditions = conditions;
-	const extensions = asStringArray(config.extensions);
-	if (extensions !== void 0) result.extensions = extensions;
-	const packages = asStringRecord(config.packages);
-	if (packages !== void 0) result.packages = packages;
-	const additionalImports = asStringRecord(config.additionalImports);
-	if (additionalImports !== void 0) result.additionalImports = additionalImports;
-	const scopes = asScopes(config.scopes);
-	if (scopes !== void 0) result.scopes = scopes;
-	const hooks = asHooks(config.hooks);
-	if (hooks !== void 0) result.hooks = hooks;
+	const result = { root: resolveRoot(asPath(config.root), configDir) };
+	assign(result, "manifest", asString(config.manifest));
+	assign(result, "out", asPath(config.out));
+	assign(result, "indent", asIndent(config.indent));
+	assign(result, "relativeTo", asPath(config.relativeTo));
+	assign(result, "conditions", asStringArray(config.conditions));
+	assign(result, "extensions", asStringArray(config.extensions));
+	assign(result, "filter", asTargetFilters(config.filter));
+	assign(result, "packages", asStringRecord(config.packages));
+	assign(result, "additionalImports", asStringRecord(config.additionalImports));
+	assign(result, "scopes", asScopes(config.scopes));
+	assign(result, "hooks", asHooks(config.hooks));
 	return result;
 }
 /**
@@ -258,12 +265,26 @@ function mergeScopes(base, overrides) {
 //#endregion
 //#region src/map.ts
 const DEFAULT_CONDITIONS = ["import", "default"];
+/** Default output filename for a written import map. */
 const DEFAULT_OUT = "import_map.json";
 const SCHEME_PREFIX = /^(jsr|npm):(?!\/)/;
+/**
+* Normalize a location to a filesystem path.
+*
+* @param value Path string, `file://` URL string, or {@link URL}.
+* @returns The filesystem path.
+*/
 function toPath(value) {
 	if (typeof value === "string") return value.startsWith("file://") ? fileURLToPath(value) : value;
 	return fileURLToPath(value.href);
 }
+/**
+* Resolve an output location against a project root.
+*
+* @param root Project root directory.
+* @param out Output location, relative or absolute.
+* @returns The absolute output path.
+*/
 function resolveOut(root, out) {
 	return path.resolve(toPath(root), toPath(out));
 }
@@ -293,17 +314,28 @@ function readManifest(manifestPath) {
 	if (!isRecord(parsed)) throw new Error(`Manifest at ${manifestPath} must be a JSON object`);
 	return parsed;
 }
-function extensionFilter(extensions) {
+function matcherKeeps(matcher, target) {
+	return matcher instanceof RegExp ? matcher.test(target) : matcher(target);
+}
+/**
+* Build a predicate deciding whether a candidate target survives: its extension must be in the
+* whitelist (if any extensions are given), and every {@link TargetFilter} must also accept it.
+*/
+function targetFilter(extensions, filters) {
 	const allowed = new Set(extensions.map((ext) => ext.startsWith(".") ? ext : `.${ext}`));
-	return (file) => allowed.has(path.extname(file));
+	return (target) => (allowed.size === 0 || allowed.has(path.extname(target))) && filters.every((matcher) => matcherKeeps(matcher, target));
 }
-function expandManifestImport(root, key, rawValue, { conditions, extensions }) {
+function expandManifestImport(root, key, rawValue, { conditions, extensions, filter }) {
 	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 };
-	const files = filesUnder(path.join(root, pattern.targetDirectory));
-	return expandPattern(pattern, extensions.length > 0 ? files.filter(extensionFilter(extensions)) : files);
+	const expanded = expandPattern(pattern, filesUnder(path.join(root, pattern.targetDirectory)));
+	if (extensions.length === 0 && filter.length === 0) return expanded;
+	const keep = targetFilter(extensions, filter);
+	const filtered = {};
+	for (const [specifier, target] of Object.entries(expanded)) if (keep(target)) filtered[specifier] = target;
+	return filtered;
 }
 function keyBaseLength(key) {
 	const star = key.indexOf("*");
@@ -374,6 +406,7 @@ function rebaseScopePrefix(root, relativeTo, scope) {
 *
 * @param options Project, manifest, condition, and rebasing options.
 * @returns A sorted import map document.
+* @category Generate
 */
 function createImportMap(options) {
 	const root = toPath(options.root);
@@ -383,37 +416,38 @@ function createImportMap(options) {
 	const relativeTo = options.relativeTo === void 0 ? root : toPath(options.relativeTo);
 	const imports = expandManifest(root, relativeTo, manifestImports, {
 		conditions,
-		extensions: options.extensions ?? []
+		extensions: options.extensions ?? [],
+		filter: options.filter ?? []
 	});
 	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));
+	const sortedScopes = sortEntries(scopes);
 	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.
+* Serialize an import map as stable JSON with a trailing newline.
 *
 * @example
 * ```ts
-* // Format an import map for stdout.
+* // Format an import map for stdout, indented with two spaces.
 * import { formatImportMap } from 'jsr:@kjanat/importmapify';
 *
-* const text = formatImportMap({
-*   imports: { '#config': './src/config.ts' },
-* });
+* const text = formatImportMap({ imports: { '#config': './src/config.ts' } }, 2);
 *
 * console.log(text);
 * ```
 *
 * @param map Import map to serialize.
+* @param indent Indentation with `JSON.stringify` space semantics; defaults to a tab.
 * @returns Formatted JSON ready to print or write.
+* @category Generate
 */
-function formatImportMap(map) {
-	return `${JSON.stringify(map, null, "	")}\n`;
+function formatImportMap(map, indent = "	") {
+	return `${JSON.stringify(map, null, indent)}\n`;
 }
 /**
 * Create an import map and write it to disk, creating parent directories as needed.
@@ -432,6 +466,7 @@ function formatImportMap(map) {
 *
 * @param options Creation options plus the optional output path.
 * @returns The absolute path of the written file.
+* @category Generate
 */
 function writeImportMap(options) {
 	const out = resolveOut(options.root, options.out ?? "import_map.json");
@@ -441,7 +476,7 @@ function writeImportMap(options) {
 		relativeTo
 	});
 	fs.mkdirSync(path.dirname(out), { recursive: true });
-	fs.writeFileSync(out, formatImportMap(map));
+	fs.writeFileSync(out, formatImportMap(map, options.indent));
 	return out;
 }
 function directoryTarget(target) {
@@ -464,6 +499,7 @@ function directoryTarget(target) {
 * @param name Bare package specifier.
 * @param target Exact target for {@link name}.
 * @returns The bare entry and its trailing-slash subpath entry.
+* @category Generate
 */
 function packageEntries(name, target) {
 	return {
@@ -487,9 +523,23 @@ function packageEntries(name, target) {
 * writeImportMap(config);
 * ```
 *
+* @example
+* ```ts
+* // Config file with a build hook: generate:before runs before the CLI scans.
+* import { execSync } from 'node:child_process';
+* import { defineConfig } from 'jsr:@kjanat/importmapify';
+*
+* export default defineConfig({
+*   hooks: {
+*     'generate:before': () => execSync('deno task build', { stdio: 'inherit' }),
+*   },
+* });
+* ```
+*
 * @param config Import map configuration; every field is optional.
-* @returns The same `config` value with its exact type preserved, so a config that includes `root` stays
+* @returns The same {@linkcode config} value with its exact type preserved, so a config that includes {@linkcode CreateImportMapOptions.root} stays
 * assignable to {@link writeImportMap} while one that omits it is still a valid config file.
+* @category Configuration
 */
 function defineConfig(config) {
 	return config;
@@ -497,7 +547,8 @@ function defineConfig(config) {
 //#endregion
 //#region src/cli.ts
 const EXAMPLE_TOKEN = /(?:'[^']*'|"[^"]*"|\S)+/g;
-const JSON_MODE = argv.includes("--json");
+const SPACE_COUNT = /^\d+$/;
+const JSON_MODE = (argv.includes("--") ? argv.slice(0, argv.indexOf("--")) : argv).includes("--json");
 function highlightExample(example) {
 	if (JSON_MODE) return example;
 	const tokens = example.match(EXAMPLE_TOKEN);
@@ -569,11 +620,34 @@ function preferExplicit(explicit, flagValue, configValue) {
 function preferArray(flagValue, configValue) {
 	return flagValue !== void 0 && flagValue.length > 0 ? flagValue : configValue;
 }
+function parseIndent(raw) {
+	if (raw === "tab") return "	";
+	if (SPACE_COUNT.test(raw)) return Number(raw);
+	throw new CLIError(`--indent expects a number of spaces or "tab", got "${raw}"`, {
+		code: "invalid-indent-flag",
+		exitCode: 2
+	});
+}
+function compileFilters(raws) {
+	return raws.map((raw) => {
+		try {
+			return new RegExp(raw);
+		} catch (cause) {
+			throw new CLIError(`--filter expects a valid regular expression, got "${raw}"`, {
+				code: "invalid-filter-flag",
+				exitCode: 2,
+				cause
+			});
+		}
+	});
+}
 /** Resolve final import map options by layering explicit flags over a discovered config over defaults. */
 async function resolveGenerateOptions(flags) {
 	const base = await loadConfigOptions(flags.root, flags.config, flags["no-config"] ?? false);
 	const conditions = preferArray(flags.condition, base.conditions);
 	const extensions = preferArray(flags.ext, base.extensions);
+	const filter = preferArray(flags.filter === void 0 ? void 0 : compileFilters(flags.filter), base.filter);
+	const indent = flags.indent === void 0 ? base.indent : parseIndent(flags.indent);
 	const options = {
 		root: preferExplicit(flags.root !== cwd(), flags.root, base.root),
 		manifest: preferExplicit(flags.manifest !== "package.json", flags.manifest, base.manifest),
@@ -588,17 +662,19 @@ async function resolveGenerateOptions(flags) {
 		},
 		scopes: mergeScopes(base.scopes, buildScopes(flags.scope ?? []))
 	};
-	if (base.relativeTo !== void 0) options.relativeTo = base.relativeTo;
-	if (conditions !== void 0) options.conditions = conditions;
-	if (extensions !== void 0) options.extensions = extensions;
-	if (base.hooks !== void 0) options.hooks = base.hooks;
+	assign(options, "relativeTo", base.relativeTo);
+	assign(options, "indent", indent);
+	assign(options, "conditions", conditions);
+	assign(options, "extensions", extensions);
+	assign(options, "filter", filter);
+	assign(options, "hooks", base.hooks);
 	return options;
 }
 /** 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(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("config", flag.string().describe("Config file path; skips discovery.").alias("C")).flag("no-config", flag.boolean().describe("Skip config file discovery.")).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.")).flag("quiet", flag.boolean().describe("Suppress the confirmation message on stderr.").alias("q")).example(highlightExample("importmapify --stdout"), "Print the generated import map").example(highlightExample(`importmapify --package 'dreamcli=jsr:@kjanat/dreamcli@^3' --scope './tests/::dreamcli/testkit=jsr:@kjanat/dreamcli@^3/testkit'`), "Add global and test-scoped dependencies").example(highlightExample("importmapify --check"), "Fail when the generated file is stale").action(async ({ 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("indent", flag.string().describe("Indentation as a number of spaces or the word \"tab\".")).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("filter", flag.array(flag.string()).describe("Regular expression a pattern target path must match. Repeatable.").alias("f")).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("config", flag.string().describe("Config file path; skips discovery.").alias("C")).flag("no-config", flag.boolean().describe("Skip config file discovery.")).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.")).flag("quiet", flag.boolean().describe("Suppress the confirmation message on stderr.").alias("q")).example(highlightExample("importmapify --stdout"), "Print the generated import map").example(highlightExample(`importmapify --package 'dreamcli=jsr:@kjanat/dreamcli@^3' --scope './tests/::dreamcli/testkit=jsr:@kjanat/dreamcli@^3/testkit'`), "Add global and test-scoped dependencies").example(highlightExample("importmapify --check"), "Fail when the generated file is stale").action(async ({ flags, out }) => {
 	const { log, warn, error, setExitCode } = out;
 	const { check, stdout, quiet } = flags;
 	if (check && stdout) throw new CLIError("--check and --stdout are mutually exclusive", {
@@ -617,7 +693,7 @@ const generateCommand = command("generate").description("Expand package.json sub
 	};
 	await options.hooks?.["generate:before"]?.(hookContext);
 	const map = createImportMap(createOptions);
-	const text = formatImportMap(map);
+	const text = formatImportMap(map, options.indent);
 	if (stdout) log(text);
 	else if (check) {
 		if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : void 0) !== text) {
@@ -637,9 +713,22 @@ const generateCommand = command("generate").description("Expand package.json sub
 //#endregion
 //#region src/mod.ts
 /**
+*
+* [![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]
+*
+* [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
+*
+*
 * Expand package import patterns into explicit Deno import map entries.
 *
-* Use the library API to create, format, or write deterministic import maps.
+* Use the library API to create, format, or write deterministic import maps that conform to the {@link https://html.spec.whatwg.org/multipage/webappapis.html#import-maps | Import Maps Standard}.
+*
 * This module also runs the `importmapify` CLI when executed directly.
 *
 * @example
@@ -651,6 +740,12 @@ const generateCommand = command("generate").description("Expand package.json sub
 * console.log(importMap.imports);
 * ```
 *
+* @example
+* ```sh
+* // Access these docs programmatically
+* deno doc jsr:@kjanat/importmapify
+* ```
+*
 * @module importmapify
 */
 const cli$1 = cli("importmapify").manifest({

package/import_map.json

@@ -7,6 +7,7 @@
 		"#src/expand": "./src/expand.ts",
 		"#src/map": "./src/map.ts",
 		"#src/mod": "./src/mod.ts",
+		"#src/types": "./src/types.ts",
 		"@types/bun": "npm:@types/bun@1.3.14",
 		"ansispeck": "jsr:@kjanat/ansispeck@0.2.0",
 		"ansispeck/": "jsr:/@kjanat/ansispeck@0.2.0/",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "1.4.0",
+	"version": "1.6.0",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",
@@ -11,7 +11,7 @@
 		"dreamcli",
 		"ansispeck"
 	],
-	"homepage": "https://github.com/kjanat/importmapify#readme",
+	"homepage": "https://importmapify.kjanat.dev",
 	"bugs": {
 		"url": "https://github.com/kjanat/importmapify/issues"
 	},