importmapify 1.1.1 → 1.3.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           |
+| `--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                 |
 | `--stdout`                  |       | Print the map instead of writing it                                       | off                 |
 
@@ -52,6 +54,28 @@ npx importmapify \
 
 Run `npx importmapify --help` for the full reference, or `npx importmapify --completions bash` for shell completions.
 
+### Config file
+
+The CLI auto-discovers a config file in the project root and uses its default export as the base options. Discovery
+order (first match wins): `importmapify.config.{mjs,cjs,js,ts,mts,cts}`, then `.importmapify.{mjs,cjs,js,ts,mts,cts}`.
+
+```js
+// importmapify.config.mjs
+export default {
+	packages: { dreamcli: 'jsr:@kjanat/dreamcli@^3' },
+	extensions: ['ts'],
+};
+```
+
+Then `npx importmapify` reads it automatically. Point at a specific file with `--config <path>`, or skip discovery 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 runtime that strips types (Bun, Deno, or Node
+
+> = 22.6), so on older Node use a `.mjs`/`.cjs`/`.js` config.
+
 ## Library
 
 ```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.1.1",
+	"version": "1.3.0",
 	"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.mjs

@@ -1,9 +1,10 @@
 #!/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 { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/expand.ts
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -116,6 +117,129 @@ function rebaseTarget(root, relativeTo, target) {
 	return relative.startsWith(".") ? relative : `./${relative}`;
 }
 //#endregion
+//#region src/config.ts
+const CONFIG_BASENAMES = ["importmapify.config", ".importmapify"];
+const CONFIG_EXTENSIONS = [
+	"mjs",
+	"cjs",
+	"js",
+	"ts",
+	"mts",
+	"cts"
+];
+/**
+* Find the first config file directly under `root`.
+*
+* Bases are tried in order (`importmapify.config`, then `.importmapify`), each across
+* `.mjs`, `.cjs`, `.js`, then the TypeScript equivalents. The first existing file wins.
+*
+* @param root Directory to search.
+* @returns The config file path, or `undefined` when none exists.
+*/
+function discoverConfig(root) {
+	for (const base of CONFIG_BASENAMES) for (const ext of CONFIG_EXTENSIONS) {
+		const candidate = path.join(root, `${base}.${ext}`);
+		if (fs.existsSync(candidate)) return candidate;
+	}
+}
+/**
+* Import a config file and return its default-exported object.
+*
+* Uses the runtime's native module loader, so a `.ts` config requires a runtime that
+* strips types (Bun, Deno, or Node >= 22.6).
+*
+* @param file Config file path.
+* @returns The default export, validated as a plain object.
+* @throws When the file cannot be imported or its default export is not a plain object.
+*/
+async function loadConfig(file) {
+	let module;
+	try {
+		module = await import(pathToFileURL(file).href);
+	} catch (cause) {
+		throw new Error(`Cannot load config at ${file}; a .ts config needs a runtime that strips types (Bun, Deno, or Node >= 22.6)`, { cause });
+	}
+	const config = isRecord(module) ? module.default : void 0;
+	if (!isRecord(config)) throw new Error(`Config at ${file} must have a default export object`);
+	return config;
+}
+function asString(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function asPath(value) {
+	return typeof value === "string" || value instanceof URL ? value : void 0;
+}
+function asStringArray(value) {
+	return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+}
+function asStringRecord(value) {
+	if (!isRecord(value)) return;
+	const record = {};
+	for (const [key, item] of Object.entries(value)) {
+		if (typeof item !== "string") return;
+		record[key] = item;
+	}
+	return record;
+}
+function asScopes(value) {
+	if (!isRecord(value)) return;
+	const scopes = {};
+	for (const [prefix, entries] of Object.entries(value)) {
+		const record = asStringRecord(entries);
+		if (record === void 0) return;
+		scopes[prefix] = record;
+	}
+	return scopes;
+}
+/**
+* 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: '.'`.
+*
+* @param config Raw default-exported config object.
+* @param configDir Directory containing the config file.
+* @returns The subset of {@link WriteImportMapOptions} the config declares.
+*/
+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;
+	const manifest = asString(config.manifest);
+	if (manifest !== void 0) result.manifest = manifest;
+	const out = asPath(config.out);
+	if (out !== void 0) result.out = out;
+	const relativeTo = asPath(config.relativeTo);
+	if (relativeTo !== void 0) result.relativeTo = relativeTo;
+	const conditions = asStringArray(config.conditions);
+	if (conditions !== void 0) result.conditions = conditions;
+	const extensions = asStringArray(config.extensions);
+	if (extensions !== void 0) result.extensions = extensions;
+	const packages = asStringRecord(config.packages);
+	if (packages !== void 0) result.packages = packages;
+	const additionalImports = asStringRecord(config.additionalImports);
+	if (additionalImports !== void 0) result.additionalImports = additionalImports;
+	const scopes = asScopes(config.scopes);
+	if (scopes !== void 0) result.scopes = scopes;
+	return result;
+}
+/**
+* Merge scope maps, with override entries winning per scope-prefix key.
+*
+* @param base Scopes from the config file.
+* @param overrides Scopes from CLI flags.
+* @returns Combined scopes.
+*/
+function mergeScopes(base, overrides) {
+	const result = {};
+	for (const [prefix, entries] of Object.entries(base ?? {})) result[prefix] = { ...entries };
+	for (const [prefix, entries] of Object.entries(overrides)) result[prefix] = {
+		...result[prefix],
+		...entries
+	};
+	return result;
+}
+//#endregion
 //#region src/map.ts
 const DEFAULT_CONDITIONS = ["import", "default"];
 const DEFAULT_OUT = "import_map.json";
@@ -355,6 +479,12 @@ function defineConfig(options) {
 }
 //#endregion
 //#region src/cli.ts
+const EXAMPLE_TOKEN = /(?:'[^']*'|"[^"]*"|\S)+/g;
+function highlightExample(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}"`, {
@@ -394,47 +524,89 @@ function buildScopes(raws) {
 	}
 	return scopes;
 }
+async function loadConfigOptions(searchRoot, configFlag, noConfig) {
+	if (noConfig) return {};
+	const file = configFlag ?? discoverConfig(searchRoot);
+	if (file === void 0) return {};
+	if (!existsSync(file)) throw new CLIError(`Config file not found: ${file}`, {
+		code: "config-not-found",
+		exitCode: 2
+	});
+	try {
+		return configToOptions(await loadConfig(file), dirname(file));
+	} catch (cause) {
+		throw new CLIError(cause instanceof Error ? cause.message : `Cannot load config at ${file}`, {
+			code: "config-load-failed",
+			exitCode: 2,
+			cause
+		});
+	}
+}
+/** Explicitly-passed flag value wins; otherwise the config value, otherwise the flag default. */
+function preferExplicit(explicit, flagValue, configValue) {
+	return explicit ? flagValue : configValue ?? flagValue;
+}
+/** A non-empty flag array wins over the config value. */
+function preferArray(flagValue, configValue) {
+	return flagValue !== void 0 && flagValue.length > 0 ? flagValue : configValue;
+}
+/** 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 options = {
+		root: preferExplicit(flags.root !== cwd(), flags.root, base.root),
+		manifest: preferExplicit(flags.manifest !== "package.json", flags.manifest, base.manifest),
+		out: preferExplicit(flags.out !== DEFAULT_OUT, flags.out, base.out),
+		packages: {
+			...base.packages,
+			...parseEntries(flags.package ?? [], "package", "invalid-package-flag")
+		},
+		additionalImports: {
+			...base.additionalImports,
+			...parseEntries(flags.import ?? [], "import", "invalid-import-flag")
+		},
+		scopes: mergeScopes(base.scopes, buildScopes(flags.scope ?? []))
+	};
+	if (base.relativeTo !== void 0) options.relativeTo = base.relativeTo;
+	if (conditions !== void 0) options.conditions = conditions;
+	if (extensions !== void 0) options.extensions = extensions;
+	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("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(({ flags, out }) => {
-	const { log, error, setExitCode } = out;
-	const { check, stdout, root, manifest, condition: cdts, out: of, import: imf, package: pkf, ext: exf, scope: scf } = 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
 	});
-	const outPath = resolveOut(root, of);
-	const relativeTo = dirname(outPath);
-	const options = {
-		root,
-		manifest,
-		conditions: cdts,
-		packages: parseEntries(pkf ?? [], "package", "invalid-package-flag"),
-		additionalImports: parseEntries(imf ?? [], "import", "invalid-import-flag"),
-		scopes: buildScopes(scf ?? []),
-		relativeTo,
-		extensions: exf
+	const options = await resolveGenerateOptions(flags);
+	const outPath = resolveOut(options.root, options.out ?? "import_map.json");
+	const createOptions = {
+		...options,
+		relativeTo: options.relativeTo ?? dirname(outPath)
 	};
 	if (stdout) {
-		log(formatImportMap(createImportMap(options)));
+		log(formatImportMap(createImportMap(createOptions)));
 		return;
 	}
 	if (check) {
-		const expected = formatImportMap(createImportMap(options));
+		const expected = formatImportMap(createImportMap(createOptions));
 		if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : void 0) !== expected) {
 			error(`${outPath} is stale`);
 			setExitCode(1);
 			return;
 		}
-		log(`${outPath} is up to date`);
+		if (!quiet) warn(`${outPath} is up to date`);
 		return;
 	}
-	log(`Wrote ${writeImportMap({
-		...options,
-		out: of
-	})}`);
+	const written = writeImportMap(options);
+	if (!quiet) warn(`Wrote ${written}`);
 });
 //#endregion
 //#region src/mod.ts
@@ -459,6 +631,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/import_map.json

@@ -3,6 +3,7 @@
 		"#deno": "./deno.json",
 		"#pkg": "./package.json",
 		"#src/cli": "./src/cli.ts",
+		"#src/config": "./src/config.ts",
 		"#src/expand": "./src/expand.ts",
 		"#src/map": "./src/map.ts",
 		"#src/mod": "./src/mod.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "1.1.1",
+	"version": "1.3.0",
 	"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": {