importmapify 1.2.0 → 1.3.1

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`    | `(config: Config) => Config`                               | 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,6 +133,8 @@ 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` is an alias for `WriteImportMapOptions` — the shape a config file's default export and `defineConfig` take.
+
 `defineConfig` returns its argument unchanged; it exists only to type a config object for export and reuse without a
 manual annotation.
 
@@ -398,11 +412,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.2.0",
+	"version": "1.3.1",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [
@@ -51,6 +51,7 @@
 	"lock": false,
 	"jsrDepsInNodeModules": false,
 	"minimumDependencyAge": {
+		"age": 0,
 		"exclude": ["jsr:@kjanat/*", "npm:@kjanat/*"]
 	}
 }

package/dist/mod.d.mts

@@ -33,6 +33,8 @@ interface WriteImportMapOptions extends CreateImportMapOptions {
    */
   readonly out?: string | URL;
 }
+/** An importmapify config: the shape a config file's default export and {@linkcode defineConfig} take. */
+type Config = WriteImportMapOptions;
 /**
  * Expand a package's exact and patterned `imports` into a Deno import map.
  *
@@ -129,9 +131,9 @@ 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, with an optional `out`.
+ * @returns The same `config` value, typed as {@link Config}.
  */
-declare function defineConfig(options: WriteImportMapOptions): WriteImportMapOptions;
+declare function defineConfig(config: Config): Config;
 //#endregion
-export { type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };
+export { type Config, type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };

package/dist/mod.mjs

@@ -1,8 +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 { argv, cwd } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/expand.ts
 function escapeRegExp(value) {
@@ -470,14 +471,22 @@ 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, with an optional `out`.
+* @returns The same `config` value, typed as {@link Config}.
 */
-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(" ");
+}
 function parseKeyValue(raw, flagName, code) {
 	const eq = raw.indexOf("=");
 	if (eq === -1) throw new CLIError(`--${flagName} expects key=value, got "${raw}"`, {
@@ -571,9 +580,9 @@ 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.")).example("importmapify --stdout", "Print the generated import map").example(`importmapify --package 'dreamcli=jsr:@kjanat/dreamcli@^3' --scope './tests/::dreamcli/testkit=jsr:@kjanat/dreamcli@^3/testkit'`, "Add global and test-scoped dependencies").example("importmapify --check", "Fail when the generated file is stale").action(async ({ flags, out }) => {
-	const { log, error, setExitCode } = out;
-	const { check, stdout } = flags;
+}).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 }) => {
+	const { log, warn, error, setExitCode } = out;
+	const { check, stdout, quiet } = flags;
 	if (check && stdout) throw new CLIError("--check and --stdout are mutually exclusive", {
 		code: "conflicting-flags",
 		exitCode: 2
@@ -595,10 +604,11 @@ const generateCommand = command("generate").description("Expand package.json sub
 			setExitCode(1);
 			return;
 		}
-		log(`${outPath} is up to date`);
+		if (!quiet) warn(`${outPath} is up to date`);
 		return;
 	}
-	log(`Wrote ${writeImportMap(options)}`);
+	const written = writeImportMap(options);
+	if (!quiet) warn(`Wrote ${written}`);
 });
 //#endregion
 //#region src/mod.ts
@@ -623,6 +633,12 @@ const cli$1 = cli("importmapify").manifest({
 	from: import.meta.url,
 	files: ["package.json", "deno.json"]
 }).links().default(generateCommand).completions({ as: "flag" });
-if (import.meta.main) cli$1.run();
+if (import.meta.main) cli$1.run({ help: {
+	hyperlinks: detectHyperlinkSupport(),
+	theme: (c) => ({
+		headerName: (input) => c.bold(c.underline(input)),
+		headerVersion: (input) => c.dim(c.underline(input))
+	})
+} });
 //#endregion
 export { createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "1.2.0",
+	"version": "1.3.1",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",
@@ -65,6 +65,7 @@
 		"volta:bump": "volta pin node@latest npm@11; node --version>.node-version; run bd"
 	},
 	"dependencies": {
+		"ansispeck": "^0.2.0",
 		"dreamcli": "npm:@kjanat/dreamcli@^3.0.0-rc.11"
 	},
 	"devDependencies": {