importmapify 1.3.1 → 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
 
@@ -109,7 +111,7 @@ const out = writeImportMap({
 
 | Export            | Signature                                                  | Purpose                                                                               |
 | ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `defineConfig`    | `(config: Config) => Config`                               | Identity helper that types a config object for export and reuse.                      |
+| `defineConfig`    | `<T extends Config>(config: T) => T`                       | 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.                        |
@@ -126,18 +128,27 @@ 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` is an alias for `WriteImportMapOptions` — the shape a config file's default export and `defineConfig` take.
+`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
 manual annotation.
 
+`hooks` are lifecycle functions the CLI runs around generation, modeled on tsdown's hooks. `generate:before` runs before
+the filesystem is scanned, so building generated targets there keeps them out of a stale map; `generate:done` runs after
+the map is emitted. Each receives `{ root, out }` (`generate:done` also gets the finished `map`) and may be async. The
+synchronous library functions ignore `hooks`.
+
 ### Recipes
 
 Add dependencies with `packages`. Each entry expands to the bare specifier plus its conformant trailing-slash entry
@@ -165,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
@@ -184,6 +206,20 @@ const map = createImportMap(config);
 const written = writeImportMap(config);
 ```
 
+Build before scanning with a `generate:before` hook, so a map that includes build output does not drop entries when it
+runs before the build:
+
+```ts
+import { execSync } from 'node:child_process';
+import { defineConfig } from 'importmapify';
+
+export default defineConfig({
+  hooks: {
+    'generate:before': () => execSync('bun run build', { stdio: 'inherit' }),
+  },
+});
+```
+
 `root`, `relativeTo`, and `out` accept a path or a `file://` URL, so `import.meta.url` needs no `.pathname`:
 
 ```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.3.1",
+	"version": "1.5.0",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [

package/dist/mod.d.mts

@@ -1,40 +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 indent?: string | number;
+}
+/**
+ * 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.
+   *
+   * @example
+   * ```ts
+   * const root = '/home/me/project';
+   * ```
+   */
+  readonly root: string;
+  /**
+   * 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.
+   *
+   * @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.
+   *
+   * @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 `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 `writeImportMap` and `createImportMap`.
+   *
+   * @example
+   * ```ts
+   * const hooks = { 'generate:before': (ctx) => console.log(ctx.root) };
+   * ```
    */
-  readonly out?: string | URL;
+  readonly hooks?: Partial<ImportMapHooks>;
 }
-/** An importmapify config: the shape a config file's default export and {@linkcode defineConfig} take. */
-type Config = WriteImportMapOptions;
+//#endregion
+//#region src/map.d.ts
 /**
  * Expand a package's exact and patterned `imports` into a Deno import map.
  *
@@ -59,24 +346,23 @@ type Config = 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.
  *
@@ -131,9 +417,23 @@ declare function packageEntries(name: string, target: string): Record<string, st
  * writeImportMap(config);
  * ```
  *
- * @param config Import map configuration, with an optional `out`.
- * @returns The same `config` value, typed as {@link 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 {@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(config: Config): Config;
+declare function defineConfig<T extends Config>(config: T): T;
 //#endregion
-export { type Config, type CreateImportMapOptions, type ImportMapDocument, 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

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { bold, cyan, detectHyperlinkSupport } from "ansispeck";
 import { CLIError, cli, command, flag } from "dreamcli";
-import fs, { existsSync, readFileSync } from "node:fs";
-import path, { dirname } from "node:path";
+import fs, { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path, { dirname, resolve } from "node:path";
 import { argv, cwd } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/expand.ts
@@ -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 = {};
@@ -191,36 +200,56 @@ function asScopes(value) {
 	}
 	return scopes;
 }
+function isHook(value) {
+	return typeof value === "function";
+}
+function asHooks(value) {
+	if (!isRecord(value)) return;
+	const hooks = {};
+	const before = value["generate:before"];
+	if (isHook(before)) hooks["generate:before"] = before;
+	const done = value["generate:done"];
+	if (isHook(done)) hooks["generate:done"] = done;
+	return hooks["generate:before"] === void 0 && hooks["generate:done"] === void 0 ? void 0 : hooks;
+}
 /**
 * Parse a raw config object into typed import map options.
 *
-* Only known fields are read; a relative string `root` is resolved against the config
-* file's own directory so a config can anchor itself with `root: '.'`.
+* Only known fields are read. An omitted `root` defaults to the config file's own directory; a relative
+* string `root` resolves against it, so a config can anchor itself with `root: '.'`.
 *
 * @param config Raw default-exported config object.
 * @param configDir Directory containing the config file.
-* @returns The subset of {@link WriteImportMapOptions} the config declares.
+* @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 = typeof root === "string" && !path.isAbsolute(root) && !root.startsWith("file://") ? path.resolve(configDir, root) : 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 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);
 	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;
 	return result;
 }
 /**
@@ -277,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("*");
@@ -367,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 ?? {});
@@ -379,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.
@@ -425,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) {
@@ -471,8 +511,22 @@ function packageEntries(name, target) {
 * writeImportMap(config);
 * ```
 *
-* @param config Import map configuration, with an optional `out`.
-* @returns The same `config` value, typed as {@link 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 {@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) {
 	return config;
@@ -480,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);
@@ -552,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),
@@ -572,15 +650,18 @@ 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;
 }
 /** 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", {
@@ -593,29 +674,36 @@ const generateCommand = command("generate").description("Expand package.json sub
 		...options,
 		relativeTo: options.relativeTo ?? dirname(outPath)
 	};
-	if (stdout) {
-		log(formatImportMap(createImportMap(createOptions)));
-		return;
-	}
-	if (check) {
-		const expected = formatImportMap(createImportMap(createOptions));
-		if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : void 0) !== expected) {
+	const hookContext = {
+		root: resolve(toPath(options.root)),
+		out: outPath
+	};
+	await options.hooks?.["generate:before"]?.(hookContext);
+	const map = createImportMap(createOptions);
+	const text = formatImportMap(map, options.indent);
+	if (stdout) log(text);
+	else if (check) {
+		if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : void 0) !== text) {
 			error(`${outPath} is stale`);
 			setExitCode(1);
-			return;
-		}
-		if (!quiet) warn(`${outPath} is up to date`);
-		return;
+		} else if (!quiet) warn(`${outPath} is up to date`);
+	} else {
+		mkdirSync(dirname(outPath), { recursive: true });
+		writeFileSync(outPath, text);
+		if (!quiet) warn(`Wrote ${outPath}`);
 	}
-	const written = writeImportMap(options);
-	if (!quiet) warn(`Wrote ${written}`);
+	await options.hooks?.["generate:done"]?.({
+		...hookContext,
+		map
+	});
 });
 //#endregion
 //#region src/mod.ts
 /**
 * Expand package import patterns into explicit Deno import map entries.
 *
-* Use the library API to create, format, or write deterministic import maps.
+* 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.3.1",
+	"version": "1.5.0",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",