@pwrs/mappa 0.0.4

package/README.md

@@ -0,0 +1,284 @@
+# Mappa
+
+The high-performance import map generator for the modern web, available as a CLI tool and Go library.
+
+**[Try the web demo](https://bennypowers.github.io/mappa/)** - Generate import maps directly in your browser.
+
+![mappa - import map generator](./docs/images/mappa.png)
+
+> *Mappa* (מַפָּה) is Hebrew for "map".
+
+Modern web applications use ES modules with bare specifiers like `import { html } from 'lit'`. Browsers need [import maps][importmaps] to resolve these specifiers to actual URLs.
+
+Mappa generates import maps from your `package.json` dependencies, pointing to your local `node_modules` paths or to a path of your choosing (like `/assets/packages/...`. It's designed to be fast, with parallel dependency resolution.
+
+## Features
+
+- **Local resolution**: Generate import maps pointing to your install node modules paths
+- **Custom URL templates**: Use any asset path with `{package}` and `{path}` variables
+- **Export maps**: Full support for package.json `exports` field including subpaths and wildcards
+- **Scopes**: Automatic scope generation for transitive dependencies
+- **Merge input maps**: Combine generated maps with manual overrides
+- **Parallel resolution**: Fast transitive dependency resolution
+
+## Installation
+
+### npm
+
+```bash
+npm install @pwrs/mappa
+```
+
+Provides both a CLI (`npx mappa generate`) and a JavaScript API:
+
+```typescript
+import { resolve } from '@pwrs/mappa';
+
+const importMap = await resolve('.', {
+  template: '/assets/packages/{package}/{path}',
+});
+```
+
+### Gentoo Linux
+
+Enable the `bennypowers` overlay, then install:
+
+```bash
+eselect repository enable bennypowers
+emaint sync -r bennypowers
+emerge dev-util/mappa
+```
+
+### From Source
+
+```bash
+go install bennypowers.dev/mappa@latest
+```
+
+## Quick Start
+
+Generate an import map for your project:
+
+```bash
+# Local paths (default)
+mappa generate
+
+# Output as HTML script tag
+mappa generate --format html
+
+# Custom asset path
+mappa generate --template "/assets/packages/{package}/{path}"
+```
+
+## CLI Reference
+
+### `mappa generate`
+
+Generate an import map from `package.json` dependencies.
+
+```
+Flags:
+  -f, --format string        Output format: json, html (default "json")
+      --include-package      Additional packages to include (repeatable)
+      --input-map string     Import map file to merge with generated output
+      --template string      URL template (default: /node_modules/{package}/{path})
+  -p, --package string       Package directory (default ".")
+  -o, --output string        Output file (default: stdout)
+```
+
+**Examples:**
+
+```bash
+# Include devDependencies
+mappa generate --include-package fuse.js --include-package vitest
+
+# Merge with manual overrides
+mappa generate --input-map manual-imports.json
+
+# Custom asset path
+mappa generate --template "/assets/packages/{package}/{path}"
+```
+
+### `mappa trace`
+
+Trace HTML files to discover ES module imports and generate minimal import maps containing only the specifiers actually used.
+
+```
+Flags:
+  -f, --format string        Output format: json, html, specifiers (default "json")
+      --template string      URL template (default: /node_modules/{package}/{path})
+      --conditions string    Export condition priority (e.g., production,browser,import,default)
+      --glob string          Glob pattern to match HTML files (e.g., "_site/**/*.html")
+  -j, --jobs int             Number of parallel workers (default: number of CPUs)
+  -p, --package string       Package directory (default ".")
+  -o, --output string        Output file (default: stdout)
+```
+
+**Examples:**
+
+```bash
+# Trace a single HTML file
+mappa trace index.html
+
+# Trace with custom template
+mappa trace index.html --template "/assets/packages/{package}/{path}"
+
+# Batch mode with glob pattern (outputs NDJSON)
+mappa trace --glob "_site/**/*.html" -j 8
+
+# Output raw traced specifiers for debugging
+mappa trace index.html --format specifiers
+```
+
+**How it works:**
+
+1. Parses HTML to find `<script type="module">` tags
+2. Uses tree-sitter to extract all `import` statements from JS modules
+3. Follows transitive dependencies through local and node_modules files
+4. Generates an import map with only the bare specifiers actually imported
+
+**Static Analysis Limitations:**
+
+The trace command uses static analysis to find imports. This means:
+
+- **Dynamic imports with variable specifiers cannot be detected.** For example:
+  ```javascript
+  // This WILL be traced
+  import '@rhds/icons/standard/web-icon.js';
+
+  // This will NOT be traced (specifier is computed at runtime)
+  const iconName = 'web-icon';
+  import(`@rhds/icons/standard/${iconName}.js`);
+  ```
+
+- To handle dynamic imports, mappa includes **trailing-slash import map keys** for all direct dependencies that have wildcard exports. For example, if your package.json lists `@rhds/icons` as a dependency and that package exports `./*`, the import map will include `"@rhds/icons/": "/assets/packages/@rhds/icons/"` to cover any dynamic imports.
+
+- The same applies to scopes: transitive dependencies with wildcard exports get trailing-slash keys so their dynamic imports work correctly.
+
+## URL Templates
+
+Templates use `{variable}` syntax for dynamic URL generation:
+
+| Variable    | Description                | Example                    |
+| ----------- | -------------------------- | -------------------------- |
+| `{package}` | Full package name          | `@scope/name` or `name` |
+| `{name}`    | Package name without scope | `name`                     |
+| `{scope}`   | Scope without @ prefix     | `scope`                    |
+| `{path}`    | File path within package   | `index.js`                 |
+
+**Examples:**
+
+```bash
+# Default (node_modules)
+--template "/node_modules/{package}/{path}"
+
+# Custom assets directory
+--template "/assets/packages/{package}/{path}"
+
+# Scoped package handling
+--template "/libs/{scope}/{name}/{path}"
+```
+
+## Performance
+
+Mappa is written in Go for speed. Benchmarked against [@jspm/generator][jspm] on a real-world project ([Red Hat Design System][rhds]):
+
+| Tool            | Time          |
+| --------------- | ------------- |
+| mappa           | 3.2ms ± 0.2ms |
+| @jspm/generator | 230ms ± 6ms   |
+
+**mappa is ~72x faster** for local import map generation.
+
+[jspm]: https://jspm.org/
+[rhds]: https://github.com/RedHat-UX/red-hat-design-system
+
+## JavaScript API
+
+The npm package includes a WASM-powered JavaScript API alongside the CLI.
+
+### `resolve(rootDir, options?)`
+
+Generate an import map from a local directory's `node_modules`:
+
+```typescript
+import { resolve } from '@pwrs/mappa';
+
+const importMap = await resolve('.', {
+  template: '/assets/packages/{package}/{path}',
+  conditions: ['browser', 'import', 'default'],
+  exclude: ['lodash'],
+});
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `template` | `string` | URL template (default: `/node_modules/{package}/{path}`) |
+| `conditions` | `string[]` | Export condition priority |
+| `includePackages` | `string[]` | Additional packages beyond dependencies |
+| `exclude` | `string[]` | Packages to exclude |
+| `inputMap` | `ImportMap` | Import map to merge (takes precedence) |
+| `optimize` | `0 \| 1` | 0=none, 1=simplify+dedup (default: 1) |
+
+### `generate(packageJson, options?)`
+
+Generate an import map from package.json contents using a CDN:
+
+```typescript
+import { generate } from '@pwrs/mappa';
+
+const importMap = await generate(
+  { dependencies: { lit: '^3.0.0' } },
+  { cdn: 'esm.sh' }
+);
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `cdn` | `"esm.sh" \| "unpkg" \| "jsdelivr"` | CDN provider |
+| `template` | `string` | Custom CDN URL template |
+| `conditions` | `string[]` | Export conditions |
+
+### `version()`
+
+Returns the WASM engine version string.
+
+## Integration Examples
+
+### 11ty / Eleventy
+
+```typescript
+import { resolve } from '@pwrs/mappa';
+
+export default async function(eleventyConfig) {
+  const importMap = await resolve('.', {
+    template: '/assets/packages/{package}/{path}',
+  });
+
+  for (const [, path] of Object.entries(importMap.imports)) {
+    const match = path.match(/^\/assets\/packages\/(@[^/]+\/[^/]+|[^/]+)/);
+    if (match) {
+      eleventyConfig.addPassthroughCopy({
+        [`node_modules/${match[1]}`]: `/assets/packages/${match[1]}`,
+      });
+    }
+  }
+
+  eleventyConfig.addTransform('importmap', (content, outputPath) => {
+    if (!outputPath?.endsWith('.html')) return content;
+
+    const script = `<script type="importmap">\n${JSON.stringify(importMap, null, 2)}\n</script>`;
+    return content.replace('</head>', `${script}\n</head>`);
+  });
+}
+```
+
+## License
+
+GPLv3
+
+[importmaps]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap

package/dist/cli.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { platform, arch } from "node:os";
+import { createRequire } from "node:module";
+import { chmodSync, accessSync, constants } from "node:fs";
+import { spawn } from "node:child_process";
+const require = createRequire(import.meta.url);
+const supportedTargets = new Set([
+    "linux-x64",
+    "linux-arm64",
+    "darwin-x64",
+    "darwin-arm64",
+    "win32-x64",
+    "win32-arm64",
+]);
+const target = `${platform()}-${arch()}`;
+if (!supportedTargets.has(target)) {
+    console.error(`mappa: Unsupported platform/arch: ${target}`);
+    process.exit(1);
+}
+let binPath;
+try {
+    binPath = require.resolve(`@pwrs/mappa-${target}/mappa${platform() === "win32" ? ".exe" : ""}`);
+}
+catch {
+    console.error(`mappa: Platform binary package @pwrs/mappa-${target} not installed. Was there an install error?`);
+    process.exit(1);
+}
+if (platform() !== "win32") {
+    try {
+        accessSync(binPath, constants.X_OK);
+    }
+    catch {
+        chmodSync(binPath, 0o755);
+    }
+}
+const child = spawn(binPath, process.argv.slice(2), { stdio: "inherit" });
+const signals = ["SIGTERM", "SIGINT", "SIGHUP"];
+signals.forEach((signal) => {
+    process.on(signal, () => {
+        child.kill(signal);
+    });
+});
+child.on("error", (err) => {
+    console.error(`mappa: Failed to spawn binary: ${err.message}`);
+    process.exit(1);
+});
+const signalNumbers = {
+    SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGTERM: 15,
+};
+child.on("exit", (code, signal) => {
+    if (signal) {
+        process.exit(128 + (signalNumbers[signal] ?? 1));
+    }
+    process.exit(code ?? 1);
+});

package/dist/mappa.d.ts

@@ -0,0 +1,56 @@
+export interface GenerateOptions {
+    /** CDN provider name */
+    cdn?: "esm.sh" | "unpkg" | "jsdelivr";
+    /** Custom CDN URL template */
+    template?: string;
+    /** Export conditions to resolve */
+    conditions?: string[];
+    /** Packages to exclude from the generated map, including as transitive dependencies */
+    exclude?: string[];
+}
+export interface ResolveOptions {
+    /** URL template (default: /node_modules/{package}/{path}) */
+    template?: string;
+    /** Export condition priority (e.g., ["production", "browser", "import", "default"]) */
+    conditions?: string[];
+    /** Additional packages to include beyond dependencies */
+    includePackages?: string[];
+    /** Packages to exclude from the generated map */
+    exclude?: string[];
+    /** Import map to merge with generated output (input map takes precedence) */
+    inputMap?: ImportMap;
+    /** Optimization level: 0=none, 1=simplify+dedup (default: 1) */
+    optimize?: 0 | 1;
+}
+export interface ImportMap {
+    imports?: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+}
+interface GoConstructor {
+    new (): {
+        run(instance: WebAssembly.Instance): void;
+        importObject: WebAssembly.Imports;
+    };
+}
+interface MappaApi {
+    generate(packageJson: string, options?: GenerateOptions): Promise<string>;
+    resolve(rootDir: string, options?: ResolveOptions): Promise<string>;
+    version: string;
+}
+declare global {
+    var Go: GoConstructor;
+    var mappa: MappaApi;
+}
+/**
+ * Generate an import map from package.json contents using a CDN resolver.
+ */
+export declare function generate(packageJson: string | Record<string, unknown>, options?: GenerateOptions): Promise<ImportMap>;
+/**
+ * Generate an import map from a local directory's node_modules.
+ */
+export declare function resolve(rootDir: string, options?: ResolveOptions): Promise<ImportMap>;
+/**
+ * Get the mappa WASM version.
+ */
+export declare function version(): Promise<string>;
+export {};

package/dist/mappa.js

@@ -0,0 +1,65 @@
+import { readFile } from "node:fs/promises";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let initPromise = null;
+async function init() {
+    if (initPromise)
+        return initPromise;
+    initPromise = (async () => {
+        await import(pathToFileURL(join(__dirname, "wasm_exec.js")).href);
+        const wasmPath = join(__dirname, "mappa.wasm");
+        const wasmBytes = await readFile(wasmPath);
+        const go = new Go();
+        const { instance } = await WebAssembly.instantiate(wasmBytes, go.importObject);
+        go.run(instance);
+        if (typeof mappa == "undefined") {
+            await new Promise((resolve, reject) => {
+                let attempts = 0;
+                const check = () => {
+                    if (typeof mappa !== "undefined") {
+                        resolve();
+                    }
+                    else if (++attempts > 100) {
+                        reject(new Error("mappa WASM failed to initialize"));
+                    }
+                    else {
+                        setTimeout(check, 10);
+                    }
+                };
+                check();
+            });
+        }
+        return mappa;
+    })().catch((err) => {
+        initPromise = null;
+        throw err;
+    });
+    return initPromise;
+}
+/**
+ * Generate an import map from package.json contents using a CDN resolver.
+ */
+export async function generate(packageJson, options) {
+    const mappa = await init();
+    const input = typeof packageJson === "string"
+        ? packageJson
+        : JSON.stringify(packageJson);
+    const resultStr = await mappa.generate(input, options);
+    return JSON.parse(resultStr);
+}
+/**
+ * Generate an import map from a local directory's node_modules.
+ */
+export async function resolve(rootDir, options) {
+    const mappa = await init();
+    const resultStr = await mappa.resolve(rootDir, options);
+    return JSON.parse(resultStr);
+}
+/**
+ * Get the mappa WASM version.
+ */
+export async function version() {
+    const mappa = await init();
+    return mappa.version;
+}

package/dist/postinstall.js

@@ -0,0 +1,21 @@
+import { platform, arch } from "node:process";
+import { spawnSync } from "node:child_process";
+const platformPackages = {
+    "darwin-x64": "@pwrs/mappa-darwin-x64",
+    "darwin-arm64": "@pwrs/mappa-darwin-arm64",
+    "linux-x64": "@pwrs/mappa-linux-x64",
+    "linux-arm64": "@pwrs/mappa-linux-arm64",
+    "win32-x64": "@pwrs/mappa-win32-x64",
+    "win32-arm64": "@pwrs/mappa-win32-arm64",
+};
+const pkg = platformPackages[`${platform}-${arch}`];
+if (!pkg) {
+    console.error(`Unsupported platform: ${platform}-${arch}. ` +
+        `Please check https://github.com/bennypowers/mappa for supported platforms.`);
+    process.exit(1);
+}
+const result = spawnSync("npm", ["install", "--no-save", pkg], { stdio: "inherit", shell: true });
+if (result.status !== 0) {
+    console.error(`Failed to install platform binary package: ${pkg}`);
+    process.exit(1);
+}