importmapify 1.3.0 → 1.4.0

package/README.md

@@ -43,6 +43,7 @@ npx importmapify --root . --out import_map.json
 | `--no-config`               |       | Skip config file discovery                                                | off                 |
 | `--check`                   |       | Exit 1 if the output file is stale, without writing it                    | off                 |
 | `--stdout`                  |       | Print the map instead of writing it                                       | off                 |
+| `--quiet`                   | `-q`  | Suppress the `Wrote <path>` confirmation (written to stderr)              | off                 |
 
 Add global and test-scoped dependencies from the CLI:
 
@@ -61,9 +62,21 @@ order (first match wins): `importmapify.config.{mjs,cjs,js,ts,mts,cts}`, then `.
 
 ```js
 // importmapify.config.mjs
+import { defineConfig } from 'importmapify';
+
+export default defineConfig({
+  packages: { dreamcli: 'jsr:@kjanat/dreamcli@^3' },
+  extensions: ['ts'],
+});
+```
+
+Or annotate a plain object, no import:
+
+```js
+/** @type {import('importmapify').Config} */
 export default {
-	packages: { dreamcli: 'jsr:@kjanat/dreamcli@^3' },
-	extensions: ['ts'],
+  packages: { dreamcli: 'jsr:@kjanat/dreamcli@^3' },
+  extensions: ['ts'],
 };
 ```
 
@@ -72,9 +85,8 @@ Then `npx importmapify` reads it automatically. Point at a specific file with `-
 
 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 runtime that strips types (Bun, Deno, or Node
-
-> = 22.6), so on older Node use a `.mjs`/`.cjs`/`.js` config.
+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
 
@@ -95,13 +107,13 @@ const out = writeImportMap({
 });
 ```
 
-| Export            | Signature                                                   | Purpose                                                                               |
-| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `defineConfig`    | `(options: WriteImportMapOptions) => WriteImportMapOptions` | Identity helper that types a config object for export and reuse.                      |
-| `createImportMap` | `(options: CreateImportMapOptions) => ImportMapDocument`    | Build the import map in memory.                                                       |
-| `formatImportMap` | `(map: ImportMapDocument) => string`                        | Serialize to the canonical sorted, tab-indented JSON text.                            |
-| `writeImportMap`  | `(options: WriteImportMapOptions) => string`                | Build, serialize, and write to disk; returns the written path.                        |
-| `packageEntries`  | `(name: string, target: string) => Record<string, string>`  | Build the bare and trailing-slash entry pair a package needs to resolve its subpaths. |
+| Export            | Signature                                                  | Purpose                                                                               |
+| ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `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.                        |
+| `packageEntries`  | `(name: string, target: string) => Record<string, string>` | Build the bare and trailing-slash entry pair a package needs to resolve its subpaths. |
 
 `CreateImportMapOptions`:
 
@@ -121,9 +133,18 @@ resolved against `root` and accepts a relative path, an absolute path, or a `fil
 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
+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
@@ -170,6 +191,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
@@ -398,11 +433,10 @@ import { writeImportMap } from 'importmapify';
 const root = '/path/to/source-tree';
 const importMap = writeImportMap({ root, out: 'import_map.json' });
 
-const documentation = execFileSync(
-  'deno',
-  ['doc', '--import-map', importMap, '--json', 'src/index.ts'],
-  { cwd: root, encoding: 'utf8' },
-);
+const documentation = execFileSync('deno', ['doc', '--import-map', importMap, '--json', 'src/index.ts'], {
+  cwd: root,
+  encoding: 'utf8',
+});
 ```
 
 ### `@deno/doc`

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.0",
+	"version": "1.4.0",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [

package/dist/mod.d.mts

@@ -33,6 +33,35 @@ interface WriteImportMapOptions extends CreateImportMapOptions {
    */
   readonly out?: string | URL;
 }
+/** Resolved paths shared by every generation hook. */
+interface HookContext {
+  /** Absolute project root that gets scanned. */
+  readonly root: string;
+  /** Absolute output path the map resolves against. */
+  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.
+ */
+interface ImportMapHooks {
+  /** Runs before the filesystem is scanned. Build pattern targets here so they exist when patterns expand. */
+  readonly "generate:before": (context: HookContext) => void | Promise<void>;
+  /** Runs after the map is generated and emitted. */
+  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.
+ * Every field is optional; the config loader and CLI supply {@linkcode CreateImportMapOptions.root | root}
+ * and the remaining defaults.
+ */
+interface Config extends Partial<WriteImportMapOptions> {
+  /** Lifecycle hooks the CLI runs around generation. Ignored by {@link writeImportMap} and {@link createImportMap}. */
+  readonly hooks?: Partial<ImportMapHooks>;
+}
 /**
  * Expand a package's exact and patterned `imports` into a Deno import map.
  *
@@ -129,9 +158,10 @@ declare function packageEntries(name: string, target: string): Record<string, st
  * writeImportMap(config);
  * ```
  *
- * @param options Import map configuration, with an optional `out`.
- * @returns The same `options` value, typed as {@link WriteImportMapOptions}.
+ * @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
+ * assignable to {@link writeImportMap} while one that omits it is still a valid config file.
  */
-declare function defineConfig(options: WriteImportMapOptions): WriteImportMapOptions;
+declare function defineConfig<T extends Config>(config: T): T;
 //#endregion
-export { type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };
+export { type Config, type CreateImportMapOptions, type HookContext, type ImportMapDocument, type ImportMapHooks, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };

package/dist/mod.mjs

@@ -1,9 +1,9 @@
 #!/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 { cwd } from "node:process";
+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
 function escapeRegExp(value) {
@@ -191,20 +191,34 @@ 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);
@@ -221,6 +235,8 @@ function configToOptions(config, configDir) {
 	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;
 }
 /**
@@ -471,16 +487,19 @@ function packageEntries(name, target) {
 * writeImportMap(config);
 * ```
 *
-* @param options Import map configuration, with an optional `out`.
-* @returns The same `options` value, typed as {@link WriteImportMapOptions}.
+* @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
+* assignable to {@link writeImportMap} while one that omits it is still a valid config file.
 */
-function defineConfig(options) {
-	return options;
+function defineConfig(config) {
+	return config;
 }
 //#endregion
 //#region src/cli.ts
 const EXAMPLE_TOKEN = /(?:'[^']*'|"[^"]*"|\S)+/g;
+const JSON_MODE = argv.includes("--json");
 function highlightExample(example) {
+	if (JSON_MODE) return example;
 	const tokens = example.match(EXAMPLE_TOKEN);
 	if (tokens === null) return example;
 	return tokens.map((token, index) => index === 0 ? bold(token) : token.startsWith("-") ? cyan(token) : token).join(" ");
@@ -572,6 +591,7 @@ async function resolveGenerateOptions(flags) {
 	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;
 	return options;
 }
 /** DreamCLI command that writes, checks, or prints an expanded Deno import map. */
@@ -591,22 +611,28 @@ 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);
+	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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",