importmapify 1.1.0 → 1.2.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
@@ -97,9 +121,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.
 
-`defineConfig` returns its argument unchanged; it exists only to type an exported config object without a manual
-annotation. Under `isolatedDeclarations`, an exported binding still needs its own annotation, so there `defineConfig`
-helps only for a config used locally rather than exported.
+`defineConfig` returns its argument unchanged; it exists only to type a config object for export and reuse without a
+manual annotation.
 
 ### Recipes
 
@@ -113,10 +136,10 @@ writeImportMap({
   root: import.meta.dirname,
   packages: {
     dreamcli: 'jsr:@kjanat/dreamcli@^3',
-    chalk: 'npm:chalk@5',
+    ansispeck: 'npm:ansispeck@^0.2',
   },
 });
-// dreamcli, dreamcli/ -> jsr:/@kjanat/dreamcli@^3/, chalk, chalk/ -> npm:/chalk@5/
+// dreamcli, dreamcli/ -> jsr:/@kjanat/dreamcli@^3/, ansispeck, ansispeck/ -> npm:/ansispeck@^0.2/
 ```
 
 Restrict pattern expansion to importable files with `extensions`, so a bare `./src/*` skips `.md`, `.json`, and other
@@ -142,7 +165,7 @@ Type a reusable config with `defineConfig` and share it across calls:
 ```ts
 import { createImportMap, defineConfig, writeImportMap } from 'importmapify';
 
-const config = defineConfig({ root: import.meta.dirname, packages: { chalk: 'npm:chalk@5' } });
+const config = defineConfig({ root: import.meta.dirname, packages: { ansispeck: 'npm:ansispeck@^0.2' } });
 const map = createImportMap(config);
 const written = writeImportMap(config);
 ```

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

package/dist/mod.mjs

@@ -3,7 +3,7 @@ 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 +116,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";
@@ -394,35 +517,79 @@ 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 }) => {
+}).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, root, manifest, condition: cdts, out: of, import: imf, package: pkf, ext: exf, scope: scf } = flags;
+	const { check, stdout } = 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);
@@ -431,10 +598,7 @@ const generateCommand = command("generate").description("Expand package.json sub
 		log(`${outPath} is up to date`);
 		return;
 	}
-	log(`Wrote ${writeImportMap({
-		...options,
-		out: of
-	})}`);
+	log(`Wrote ${writeImportMap(options)}`);
 });
 //#endregion
 //#region src/mod.ts

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