importmapify 1.4.0 → 1.5.0

package/README.md

@@ -39,6 +39,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 +86,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 +128,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 +176,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.5.0",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [

package/dist/mod.d.mts

@@ -1,67 +1,327 @@
-//#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' } },
+ * };
+ * ```
+ */
 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);
+ * ```
+ */
+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)/];
+ * ```
+ */
+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);
+ * ```
+ */
 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);
+ * ```
+ */
 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}`);
+ * ```
+ */
 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' }),
+ *   },
+ * });
+ * ```
  */
 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'],
+ * });
+ * ```
  */
 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.
  *
@@ -86,24 +346,23 @@ interface Config extends Partial<WriteImportMapOptions> {
  */
 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.
  */
-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.
  *
@@ -158,10 +417,23 @@ 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.
  */
 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

@@ -169,9 +169,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 = {};
@@ -223,12 +232,16 @@ function configToOptions(config, configDir) {
 	if (manifest !== void 0) result.manifest = manifest;
 	const out = asPath(config.out);
 	if (out !== void 0) result.out = out;
+	const indent = asIndent(config.indent);
+	if (indent !== void 0) result.indent = indent;
 	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 filter = asTargetFilters(config.filter);
+	if (filter !== void 0) result.filter = filter;
 	const packages = asStringRecord(config.packages);
 	if (packages !== void 0) result.packages = packages;
 	const additionalImports = asStringRecord(config.additionalImports);
@@ -293,17 +306,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("*");
@@ -383,7 +407,8 @@ 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 ?? {});
@@ -395,25 +420,24 @@ function createImportMap(options) {
 	};
 }
 /**
-* 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.
 */
-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.
@@ -441,7 +465,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) {
@@ -487,8 +511,21 @@ 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.
 */
 function defineConfig(config) {
@@ -497,7 +534,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 +607,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),
@@ -589,8 +650,10 @@ async function resolveGenerateOptions(flags) {
 		scopes: mergeScopes(base.scopes, buildScopes(flags.scope ?? []))
 	};
 	if (base.relativeTo !== void 0) options.relativeTo = base.relativeTo;
+	if (indent !== void 0) options.indent = indent;
 	if (conditions !== void 0) options.conditions = conditions;
 	if (extensions !== void 0) options.extensions = extensions;
+	if (filter !== void 0) options.filter = filter;
 	if (base.hooks !== void 0) options.hooks = base.hooks;
 	return options;
 }
@@ -598,7 +661,7 @@ async function resolveGenerateOptions(flags) {
 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 +680,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) {
@@ -639,7 +702,8 @@ const generateCommand = command("generate").description("Expand package.json sub
 /**
 * 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

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.5.0",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",