importmapify 1.5.0 → 1.6.0

package/README.md

@@ -21,12 +21,14 @@ per matched source file instead. This package performs that expansion and writes
 
 ```sh
 npm install importmapify
+deno add jsr:@kjanat/importmapify
 ```
 
 ## CLI
 
 ```sh
 npx importmapify --root . --out import_map.json
+deno run -A jsr:@kjanat/importmapify [...]
 ```
 
 | Flag                        | Alias | Meaning                                                                   | Default             |

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.5.0",
+	"version": "1.6.0",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [
@@ -16,26 +16,38 @@
 	"compilerOptions": {
 		"lib": ["ESNext", "DOM", "deno.ns"]
 	},
-	"importMap": "./import_map.json",
+	"importMap": "import_map.json",
 	"license": "MIT",
 	"tasks": {
 		"build": {
-			"description": "build for npm distribution",
-			"command": "bun run build",
-			"files": ["src/**", "package.json", "bun.lock"],
-			"output": ["dist/**", "deno.json"]
+			"description": "build for npm distribution (requires bun)",
+			"command": "bun run build"
 		},
 		"publish": {
 			"command": "deno publish --config deno.json --allow-dirty",
-			"description": "Publish package to jsr",
-			"dependencies": ["importmapify"]
+			"description": "Publish package to jsr"
 		},
 		"importmapify": {
-			"description": "generate importmap for deno",
-			"command": "bun scripts/generate-importmap.ts",
-			"files": ["package.json", "scripts/generate-importmap.ts", "src/**"],
-			"output": ["import_map.json"]
-		}
+			"description": "generate importmap for deno (requires bun)",
+			"command": "bun scripts/generate-importmap.ts"
+		},
+		"doc:html": {
+			"command": "sh -c 'set -e; root=$PWD; [ -f dist/mod.d.mts ] || bun run build; tmp=$(mktemp -d); { awk \"NR>1{print} /\\*\\//{if(NR>1) exit}\" src/mod.ts; cat dist/mod.d.mts; } > \"$tmp/importmapify.d.ts\"; cd \"$tmp\"; deno doc --html --name=\"$(jq -r .name \"$root/package.json\")\" --category-docs=\"$root/category-docs.json\" --output=\"$root/.denodocs/\" ./importmapify.d.ts; cd \"$root\"; deno doc --json $(jq -r \".exports | .[]? // .\" deno.json) > \"$tmp/nodes.json\" 2>/dev/null; bun scripts/link-source-buttons.mjs .denodocs \"$tmp/nodes.json\" \"$(git rev-parse HEAD)\"; bun scripts/inject-favicon.mjs .denodocs assets/favicon.svg; bunx vite-svg-to-ico generate assets/favicon.svg --out-dir .denodocs; rm -rf \"$tmp\"'",
+			"description": "generate categorized HTML docs into .denodocs (requires bun)"
+		},
+		"doc:json": {
+			"command": "mkdir -p .denodocs && deno doc --name=\"$(jq -r .name package.json)\" --json $(jq -r '.exports | .[]? // .' deno.json) > .denodocs/documentation.json",
+			"description": "emit JSON doc nodes into .denodocs"
+		},
+		"doc:lint": {
+			"command": "deno doc --lint $(jq -r '.exports | .[]? // .' deno.json)",
+			"description": "lint docs on exported symbols"
+		},
+		"format:docs": {
+			"command": "bunx dprint fmt --includes-override '.denodocs/**/*.{html,css,js,json}' --excludes-override='!.denodocs/**/*.{html,css,js,json}' --no-gitignore --allow-no-files",
+			"description": "format the output docs (requires bun)"
+		},
+		"ci:docs": "run -s doc:html doc:json format:docs"
 	},
 	"lint": {
 		"rules": {
@@ -43,7 +55,7 @@
 		}
 	},
 	"preferPackageJson": false,
-	"homepage": "https://github.com/kjanat/importmapify#readme",
+	"homepage": "https://importmapify.kjanat.dev",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/kjanat/importmapify.git"

package/dist/mod.d.mts

@@ -12,6 +12,7 @@
  *   scopes: { './tests/': { '#lib/bytes': './tests/stub/bytes.ts' } },
  * };
  * ```
+ * @category Generate
  */
 interface ImportMapDocument {
   /**
@@ -45,6 +46,7 @@ interface ImportMapDocument {
  *
  * const root: PathOrUrl = new URL('..', import.meta.url);
  * ```
+ * @category Options
  */
 type PathOrUrl = string | URL;
 /**
@@ -58,6 +60,7 @@ type PathOrUrl = string | URL;
  * // Drop hashed internal chunks like ./dist/internal-qo9O8jzH.js.
  * const filter: readonly TargetFilter[] = [/^(?!.*internal)/];
  * ```
+ * @category Options
  */
 type TargetFilter = RegExp | ((target: string) => boolean);
 /**
@@ -75,6 +78,7 @@ type TargetFilter = RegExp | ((target: string) => boolean);
  *
  * createImportMap(options);
  * ```
+ * @category Options
  */
 interface CreateImportMapOptions {
   /**
@@ -194,6 +198,7 @@ interface CreateImportMapOptions {
  *
  * writeImportMap(options);
  * ```
+ * @category Options
  */
 interface WriteImportMapOptions extends CreateImportMapOptions {
   /**
@@ -232,6 +237,7 @@ interface WriteImportMapOptions extends CreateImportMapOptions {
  *
  * const logRoot = (ctx: HookContext) => console.log(`scanning ${ctx.root}, writing ${ctx.out}`);
  * ```
+ * @category Configuration
  */
 interface HookContext {
   /**
@@ -270,6 +276,7 @@ interface HookContext {
  *   },
  * });
  * ```
+ * @category Configuration
  */
 interface ImportMapHooks {
   /**
@@ -308,6 +315,7 @@ interface ImportMapHooks {
  *   extensions: ['ts'],
  * });
  * ```
+ * @category Configuration
  */
 interface Config extends Partial<WriteImportMapOptions> {
   /**
@@ -343,6 +351,7 @@ interface Config extends Partial<WriteImportMapOptions> {
  *
  * @param options Project, manifest, condition, and rebasing options.
  * @returns A sorted import map document.
+ * @category Generate
  */
 declare function createImportMap(options: CreateImportMapOptions): ImportMapDocument;
 /**
@@ -361,6 +370,7 @@ declare function createImportMap(options: CreateImportMapOptions): ImportMapDocu
  * @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.
+ * @category Generate
  */
 declare function formatImportMap(map: ImportMapDocument, indent?: string | number): string;
 /**
@@ -380,6 +390,7 @@ declare function formatImportMap(map: ImportMapDocument, indent?: string | numbe
  *
  * @param options Creation options plus the optional output path.
  * @returns The absolute path of the written file.
+ * @category Generate
  */
 declare function writeImportMap(options: WriteImportMapOptions): string;
 /**
@@ -399,6 +410,7 @@ declare function writeImportMap(options: WriteImportMapOptions): string;
  * @param name Bare package specifier.
  * @param target Exact target for {@link name}.
  * @returns The bare entry and its trailing-slash subpath entry.
+ * @category Generate
  */
 declare function packageEntries(name: string, target: string): Record<string, string>;
 /**
@@ -433,6 +445,7 @@ declare function packageEntries(name: string, target: string): Record<string, st
  * @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.
+ * @category Configuration
  */
 declare function defineConfig<T extends Config>(config: T): T;
 //#endregion

package/dist/mod.mjs

@@ -118,6 +118,10 @@ function rebaseTarget(root, relativeTo, target) {
 }
 //#endregion
 //#region src/config.ts
+/** Set `key` on `target` unless the value is `undefined`, keeping the key/value pairing type-checked. */
+function assign(target, key, value) {
+	if (value !== void 0) target[key] = value;
+}
 const CONFIG_BASENAMES = ["importmapify.config", ".importmapify"];
 const CONFIG_EXTENSIONS = [
 	"mjs",
@@ -200,6 +204,11 @@ function asScopes(value) {
 	}
 	return scopes;
 }
+function resolveRoot(root, configDir) {
+	if (root === void 0) return configDir;
+	if (typeof root === "string" && !path.isAbsolute(root) && !root.startsWith("file://")) return path.resolve(configDir, root);
+	return root;
+}
 function isHook(value) {
 	return typeof value === "function";
 }
@@ -223,33 +232,18 @@ function asHooks(value) {
 * @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 = 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;
+	const result = { root: resolveRoot(asPath(config.root), configDir) };
+	assign(result, "manifest", asString(config.manifest));
+	assign(result, "out", asPath(config.out));
+	assign(result, "indent", asIndent(config.indent));
+	assign(result, "relativeTo", asPath(config.relativeTo));
+	assign(result, "conditions", asStringArray(config.conditions));
+	assign(result, "extensions", asStringArray(config.extensions));
+	assign(result, "filter", asTargetFilters(config.filter));
+	assign(result, "packages", asStringRecord(config.packages));
+	assign(result, "additionalImports", asStringRecord(config.additionalImports));
+	assign(result, "scopes", asScopes(config.scopes));
+	assign(result, "hooks", asHooks(config.hooks));
 	return result;
 }
 /**
@@ -271,12 +265,26 @@ function mergeScopes(base, overrides) {
 //#endregion
 //#region src/map.ts
 const DEFAULT_CONDITIONS = ["import", "default"];
+/** Default output filename for a written import map. */
 const DEFAULT_OUT = "import_map.json";
 const SCHEME_PREFIX = /^(jsr|npm):(?!\/)/;
+/**
+* Normalize a location to a filesystem path.
+*
+* @param value Path string, `file://` URL string, or {@link URL}.
+* @returns The filesystem path.
+*/
 function toPath(value) {
 	if (typeof value === "string") return value.startsWith("file://") ? fileURLToPath(value) : value;
 	return fileURLToPath(value.href);
 }
+/**
+* Resolve an output location against a project root.
+*
+* @param root Project root directory.
+* @param out Output location, relative or absolute.
+* @returns The absolute output path.
+*/
 function resolveOut(root, out) {
 	return path.resolve(toPath(root), toPath(out));
 }
@@ -398,6 +406,7 @@ function rebaseScopePrefix(root, relativeTo, scope) {
 *
 * @param options Project, manifest, condition, and rebasing options.
 * @returns A sorted import map document.
+* @category Generate
 */
 function createImportMap(options) {
 	const root = toPath(options.root);
@@ -413,7 +422,7 @@ function createImportMap(options) {
 	for (const [key, value] of Object.entries(collectAdditional(options))) imports[key] = rebaseTarget(root, relativeTo, value);
 	const scopes = buildScopes$1(root, relativeTo, options.scopes ?? {});
 	const sortedImports = sortEntries(imports);
-	const sortedScopes = Object.fromEntries(Object.entries(scopes).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+	const sortedScopes = sortEntries(scopes);
 	return Object.keys(sortedScopes).length === 0 ? { imports: sortedImports } : {
 		imports: sortedImports,
 		scopes: sortedScopes
@@ -435,6 +444,7 @@ function createImportMap(options) {
 * @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.
+* @category Generate
 */
 function formatImportMap(map, indent = "	") {
 	return `${JSON.stringify(map, null, indent)}\n`;
@@ -456,6 +466,7 @@ function formatImportMap(map, indent = "	") {
 *
 * @param options Creation options plus the optional output path.
 * @returns The absolute path of the written file.
+* @category Generate
 */
 function writeImportMap(options) {
 	const out = resolveOut(options.root, options.out ?? "import_map.json");
@@ -488,6 +499,7 @@ function directoryTarget(target) {
 * @param name Bare package specifier.
 * @param target Exact target for {@link name}.
 * @returns The bare entry and its trailing-slash subpath entry.
+* @category Generate
 */
 function packageEntries(name, target) {
 	return {
@@ -527,6 +539,7 @@ function packageEntries(name, target) {
 * @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.
+* @category Configuration
 */
 function defineConfig(config) {
 	return config;
@@ -649,12 +662,12 @@ 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;
+	assign(options, "relativeTo", base.relativeTo);
+	assign(options, "indent", indent);
+	assign(options, "conditions", conditions);
+	assign(options, "extensions", extensions);
+	assign(options, "filter", filter);
+	assign(options, "hooks", base.hooks);
 	return options;
 }
 /** DreamCLI command that writes, checks, or prints an expanded Deno import map. */
@@ -700,10 +713,22 @@ const generateCommand = command("generate").description("Expand package.json sub
 //#endregion
 //#region src/mod.ts
 /**
+*
+* [![NPM](https://img.shields.io/npm/v/importmapify?logo=npm&labelColor=CB3837&color=black)][npm]
+* [![JSR](https://img.shields.io/jsr/v/@kjanat/importmapify?logoColor=083344&logo=jsr&logoSize=auto&label=&labelColor=f7df1e&color=black)][jsr]
+* [![CI](https://github.com/kjanat/importmapify/actions/workflows/publish.yml/badge.svg)][ci]
+* [![Socket](https://badge.socket.dev/npm/package/importmapify)][socket]
+*
+* [ci]: https://github.com/kjanat/importmapify/actions/workflows/publish.yml
+* [npm]: https://npm.im/importmapify
+* [jsr]: https://jsr.io/@kjanat/importmapify
+* [socket]: https://socket.dev/npm/package/importmapify
+*
+*
 * Expand package import patterns into explicit Deno import map entries.
 *
-* 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}.
+* 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
@@ -715,6 +740,12 @@ const generateCommand = command("generate").description("Expand package.json sub
 * console.log(importMap.imports);
 * ```
 *
+* @example
+* ```sh
+* // Access these docs programmatically
+* deno doc jsr:@kjanat/importmapify
+* ```
+*
 * @module importmapify
 */
 const cli$1 = cli("importmapify").manifest({

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "1.5.0",
+	"version": "1.6.0",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",
@@ -11,7 +11,7 @@
 		"dreamcli",
 		"ansispeck"
 	],
-	"homepage": "https://github.com/kjanat/importmapify#readme",
+	"homepage": "https://importmapify.kjanat.dev",
 	"bugs": {
 		"url": "https://github.com/kjanat/importmapify/issues"
 	},