mappel 0.1.0 → 0.3.0

package/README.md

@@ -8,16 +8,28 @@ It resolves each specifier through the package's own exports map — nested cond
 
 A repo declares named layers in importmap.config.mjs, and a layer can exclude what another already resolves, so a page loads two maps and neither repeats the other. Layers can also drop a whole scope by prefix. A css specifier maps to a `.js` sibling that adds the file as a link, because a browser cannot import a stylesheet as a module. Pass `--css link` to get the specifier mapped away and the link tags printed instead.
 
+Every map is written twice: `name.json` and `name.js`, which installs the map when a page loads it with a script tag. The script must come before the first module script in the page, or it is ignored. Inline maps are registered when their element is inserted, and multiple maps in one page require Chromium 133 or newer.
+
 ```sh
-mappel --layer min                          # to stdout, urls pinned to installed versions
-mappel --layer components --split dist/     # one file per package in the layer
-mappel --layer foundation --target local    # workspace paths, for a dev server
-mappel --layer min --html                   # ready to paste into a page
+mappel                                  # every layer, to the out in the config
+mappel --no-js                          # the json only, without the script siblings
+mappel --layer min                      # one layer, to stdout
+mappel --layer min --html               # ready to paste into a page
+mappel --layer min --dist-tag alpha     # follow a channel instead of pinning
+mappel --config packages/cdn/mappel.config.mjs --out dist
 ```
 
+An option given on the command line wins; the config supplies what the command line
+does not. With no arguments it looks for `mappel.config.mjs` from the current
+directory upwards, so a package's build script is just `mappel`.
+
 ```js
-// importmap.config.mjs
+// mappel.config.mjs
 export default {
+  out: 'packages/cdn/dist',        // relative to this file
+  workspaces: ['packages'],
+  split: { components: 'components' },   // a file per package in that layer
+  js: false,                             // skip the script siblings
   layers: {
     base: { packages: ['@scope/core', '@scope/dom'] },
     extra: { packages: ['@scope/extra'], excludes: ['base'] },

package/bin/mappel.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// Write the import maps a workspace declares.
+//
+//   mappel                          every layer in mappel.config.mjs, to its `out`
+//   mappel --layer min              one layer, to stdout
+//   mappel --config packages/cdn/mappel.config.mjs --out dist
+//   mappel --layer min --dist-tag alpha --html
+//   mappel --no-js                  maps only, without their script siblings
+//
+// With no arguments it finds mappel.config.mjs by walking up from the current
+// directory, so a package's build script is just `mappel`. Every map is written
+// twice: `<name>.json` to read, and `<name>.js` to load from a page.
+
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { buildLayer, writeAll, writeMap, subpathsOf } from '../src/index.mjs';
+
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = argv.indexOf(`--${name}`);
+  return i === -1 ? fallback : argv[i + 1];
+};
+const has = (name) => argv.includes(`--${name}`);
+
+const NAMES = ['mappel.config.mjs', 'mappel.config.js', 'importmap.config.mjs'];
+
+function findConfig(from) {
+  let dir = resolvePath(from);
+  while (true) {
+    for (const name of NAMES) {
+      const candidate = join(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const explicit = flag('config', null);
+const configPath = explicit ? resolvePath(explicit) : findConfig(process.cwd());
+if (!configPath) {
+  process.stderr.write(
+    `[mappel] no ${NAMES[0]} here or above ${process.cwd()}\n` +
+      `  point at one with --config, or see https://github.com/bambiste/mappel\n`,
+  );
+  process.exit(2);
+}
+
+let config;
+try {
+  config = (await import(pathToFileURL(configPath).href)).default;
+} catch (error) {
+  process.stderr.write(`[mappel] cannot read ${configPath}\n  ${error.message}\n`);
+  process.exit(2);
+}
+
+// The config lives at the root of what it describes unless it says otherwise, so
+// a path in it reads relative to the file rather than to where this was run from.
+const base = dirname(configPath);
+const root = resolvePath(flag('root', config.root ? join(base, config.root) : base));
+
+const options = {
+  root,
+  target: flag('target', config.target ?? 'cdn'),
+  cdn: flag('cdn', config.cdn ?? 'https://unpkg.com'),
+  css: flag('css', config.css ?? 'loader'),
+  distTag: flag('dist-tag', config.distTag ?? null),
+  workspaces: config.workspaces ?? ['packages'],
+};
+
+const layerName = flag('layer', null);
+const splitInto = flag('split', null);
+
+// Each map gets a script sibling that installs it. `--no-js` writes only JSON.
+const settings = { ...config, js: has('no-js') ? false : has('js') ? true : config.js };
+
+if (!layerName && !splitInto) {
+  const out = resolvePath(flag('out', config.out ? join(base, config.out) : join(base, 'dist')));
+  const written = writeAll(settings, { ...options, out });
+  for (const { file, entries, split } of written) {
+    process.stderr.write(`  ${file} — ${entries} ${split ? 'files' : 'entries'}\n`);
+  }
+  process.exit(0);
+}
+
+if (splitInto) {
+  const dir = resolvePath(splitInto);
+  mkdirSync(dir, { recursive: true });
+  const layer = config.layers[layerName];
+  const names =
+    typeof layer.packages === 'function'
+      ? layer.packages({ subpathsOf: (n) => subpathsOf(root, n, options.workspaces), root })
+      : layer.packages;
+  let written = 0;
+  for (const name of names) {
+    const one = buildLayer(
+      layerName,
+      { ...config, layers: { ...config.layers, [layerName]: { ...layer, packages: [name] } } },
+      options,
+    );
+    if (Object.keys(one.imports).length === 0) continue;
+    writeMap(join(dir, name.split('/').pop() + '.json'), one.imports, settings);
+    written += 1;
+  }
+  process.stderr.write(`wrote ${written} maps to ${dir}\n`);
+  process.exit(0);
+}
+
+const { imports, stylesheets, unresolved } = buildLayer(layerName, config, options);
+const json = JSON.stringify({ imports }, null, 2);
+const out = flag('out', null);
+
+if (out) {
+  if (out.endsWith('.json')) writeMap(out, imports, settings);
+  else writeFileSync(out, json + '\n');
+  process.stderr.write(`wrote ${out} — ${Object.keys(imports).length} entries\n`);
+} else if (has('html')) {
+  const links =
+    options.css === 'link' ? stylesheets.map((h) => `<link rel="stylesheet" href="${h}" />`).join('\n') : '';
+  process.stdout.write(`<script type="importmap">\n${json}\n</script>\n${links ? links + '\n' : ''}`);
+} else {
+  process.stdout.write(json + '\n');
+}
+
+if (unresolved.length) {
+  process.stderr.write('\nnot in the map (check they are installed):\n');
+  for (const u of unresolved.sort()) process.stderr.write(`  ${u}\n`);
+}

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "mappel",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "generate the import map a page needs from a workspace: resolves every transitive subpath through each package exports map, in layers that compose",
   "type": "module",
   "bin": {
-    "mappel": "./bin/import-map.mjs",
-    "import-map": "./bin/import-map.mjs"
+    "mappel": "./bin/mappel.mjs"
   },
   "exports": {
     ".": "./src/index.mjs",

package/src/index.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join, normalize, relative } from 'node:path';
 import { manifest, packageDir, resolveExport, splitSpecifier, subpathsOf } from './resolve.mjs';
 
@@ -25,7 +25,18 @@ function scanImports(file) {
  * mapped to a url a browser can fetch.
  */
 export function collect(specifiers, options) {
-  const { root, target = 'cdn', cdn = 'https://unpkg.com', css = 'loader', workspaces } = options;
+  const {
+    root,
+    target = 'cdn',
+    cdn = 'https://unpkg.com',
+    css = 'loader',
+    workspaces,
+    // The version in the url. A manifest version pins the map to exactly what was
+    // installed when it was written, which is what a published map wants. A dist
+    // tag follows a channel instead, so a page tracks it without being rebuilt —
+    // at the cost of the page changing when the channel does.
+    distTag = null,
+  } = options;
   const imports = {};
   const stylesheets = new Set();
   const unresolved = new Set();
@@ -33,9 +44,9 @@ export function collect(specifiers, options) {
 
   const urlFor = (name, dir, file) => {
     const clean = file.replace(/^\.\//, '');
-    return target === 'local'
-      ? '/' + relative(root, join(dir, clean)).split('\\').join('/')
-      : `${cdn}/${name}@${manifest(dir).version}/${clean}`;
+    if (target === 'local') return '/' + relative(root, join(dir, clean)).split('\\').join('/');
+    const version = distTag === 'none' ? '' : '@' + (distTag || manifest(dir).version);
+    return `${cdn}/${name}${version}/${clean}`;
   };
 
   const add = (spec) => {
@@ -118,3 +129,94 @@ function helpers(options) {
 }
 
 export { subpathsOf, packageDir, resolveExport };
+
+/**
+ * The script sibling of a map. A page that cannot write JSON into its own
+ * markup — a docs site, a playground, anything served as a template — gets the
+ * map by loading one classic script instead.
+ *
+ * An inline map is registered when the element is inserted, so a second file
+ * cannot merge into the first one's element and each installs its own. Several
+ * maps in one page need Chromium 133 or newer; the combined file is the way to
+ * stay on one.
+ */
+function installer(imports) {
+  const map = JSON.stringify(JSON.stringify({ imports }));
+  return `(function(){var d=document,w=function(m){if(typeof console!=='undefined')console.warn('[mappel] '+m)};
+if(d.querySelector('script[type="module"]'))w('the import map is being added after a module script and will not be used — load this file first');
+var s=d.createElement('script');s.type='importmap';s.setAttribute('data-mappel','');s.textContent=${map};
+s.addEventListener('error',function(){w('the browser rejected this import map — a page with several maps needs Chromium 133+, so use the combined map instead')});
+(d.head||d.documentElement).appendChild(s);
+(self.__mappel||(self.__mappel=[])).push(JSON.parse(s.textContent))})();
+`;
+}
+
+export function writeMap(file, imports, config = {}) {
+  writeFileSync(file, JSON.stringify({ imports }, null, 2) + '\n');
+  if (config.js !== false) writeFileSync(file.replace(/\.json$/, '.js'), installer(imports));
+}
+
+/**
+ * Write every layer a config declares, plus any per-item split it asks for.
+ * This is what `mappel` does with no arguments: the config says where the
+ * workspace is and where the files go, so a repo needs no script of its own.
+ */
+export function writeAll(config, options) {
+  const out = options.out;
+  mkdirSync(out, { recursive: true });
+
+  const written = [];
+  for (const name of Object.keys(config.layers)) {
+    const { imports } = buildLayer(name, config, options);
+    const file = join(out, `${name}.json`);
+    writeMap(file, imports, config);
+    written.push({ file, entries: Object.keys(imports).length });
+  }
+
+  // A combined file, for engines that take only one import map. Several maps in
+  // one page need Chromium 133 or newer. A layer of the same name means the config
+  // already has one, and writing both would silently overwrite the layer's file.
+  const combined = config.full === true || config.full === undefined ? 'full' : config.full;
+  if (config.full !== false && config.layers[combined]) {
+    throw new Error(
+      `[mappel] a layer is named "${combined}" and the combined file would overwrite it. ` +
+        `Set full: false, or full: "<other-name>".`,
+    );
+  }
+  if (config.full !== false) {
+    const imports = {};
+    for (const name of Object.keys(config.layers)) {
+      Object.assign(imports, buildLayer(name, config, options).imports);
+    }
+    const file = join(out, `${combined}.json`);
+    writeMap(file, sorted(imports), config);
+    written.push({ file, entries: Object.keys(imports).length });
+  }
+
+  for (const [layerName, target] of Object.entries(config.split ?? {})) {
+    const dir = join(out, target);
+    mkdirSync(dir, { recursive: true });
+    const layer = config.layers[layerName];
+    const names =
+      typeof layer.packages === 'function'
+        ? layer.packages({
+            subpathsOf: (n) => subpathsOf(options.root, n, options.workspaces),
+            root: options.root,
+          })
+        : layer.packages;
+    let count = 0;
+    for (const name of names) {
+      const one = buildLayer(
+        layerName,
+        { ...config, layers: { ...config.layers, [layerName]: { ...layer, packages: [name] } } },
+        options,
+      );
+      if (Object.keys(one.imports).length === 0) continue;
+      writeMap(join(dir, name.split('/').pop() + '.json'), one.imports, config);
+      count += 1;
+    }
+    written.push({ file: `${dir}/*.json`, entries: count, split: true });
+  }
+
+  return written;
+}

package/bin/import-map.mjs

@@ -1,92 +0,0 @@
-#!/usr/bin/env node
-// Emit the import map a page needs, from the layers a repo defines.
-//
-//   import-map --layer min
-//   import-map --layer components --split dist/components
-//   import-map --layer foundation --target local --html
-//
-// Layers come from importmap.config.mjs in the repo this runs in, so the tool
-// stays generic and the policy stays where it belongs.
-
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join, resolve as resolvePath } from 'node:path';
-import { pathToFileURL } from 'node:url';
-import { buildLayer, subpathsOf } from '../src/index.mjs';
-
-const argv = process.argv.slice(2);
-const flag = (name, fallback) => {
-  const i = argv.indexOf(`--${name}`);
-  return i === -1 ? fallback : argv[i + 1];
-};
-const has = (name) => argv.includes(`--${name}`);
-
-// The repo being scanned, not where this tool is installed — it lives in
-// node_modules, and every path it resolves hangs off this.
-const root = resolvePath(flag('root', process.cwd()));
-const configPath = resolvePath(flag('config', join(root, 'importmap.config.mjs')));
-
-let config;
-try {
-  config = (await import(pathToFileURL(configPath).href)).default;
-} catch (error) {
-  process.stderr.write(`[import-map] cannot read ${configPath}\n  ${error.message}\n`);
-  process.exit(2);
-}
-
-const options = {
-  root,
-  target: flag('target', 'cdn'),
-  cdn: flag('cdn', 'https://unpkg.com'),
-  css: flag('css', 'loader'),
-  workspaces: config.workspaces ?? ['packages'],
-};
-
-const layerName = flag('layer', Object.keys(config.layers)[0]);
-const splitInto = flag('split', null);
-
-if (splitInto) {
-  const layer = config.layers[layerName];
-  const names =
-    typeof layer.packages === 'function'
-      ? layer.packages({ subpathsOf: (n) => subpathsOf(root, n, options.workspaces), root })
-      : layer.packages;
-  mkdirSync(splitInto, { recursive: true });
-  let written = 0;
-  for (const name of names) {
-    const one = buildLayer(
-      layerName,
-      { ...config, layers: { ...config.layers, [layerName]: { ...layer, packages: [name] } } },
-      options,
-    );
-    if (Object.keys(one.imports).length === 0) continue;
-    writeFileSync(
-      join(splitInto, name.split('/').pop() + '.json'),
-      JSON.stringify({ imports: one.imports }, null, 2) + '\n',
-    );
-    written += 1;
-  }
-  process.stderr.write(`wrote ${written} maps to ${splitInto}\n`);
-  process.exit(0);
-}
-
-const { imports, stylesheets, unresolved } = buildLayer(layerName, config, options);
-const json = JSON.stringify({ imports }, null, 2);
-
-const out = flag('out', null);
-if (out) {
-  writeFileSync(out, json + '\n');
-  process.stderr.write(`wrote ${out} — ${Object.keys(imports).length} entries\n`);
-} else if (has('html')) {
-  const links =
-    options.css === 'link'
-      ? stylesheets.map((href) => `<link rel="stylesheet" href="${href}" />`).join('\n')
-      : '';
-  process.stdout.write(`<script type="importmap">\n${json}\n</script>\n${links ? links + '\n' : ''}`);
-} else {
-  process.stdout.write(json + '\n');
-}
-
-if (unresolved.length) {
-  process.stderr.write('\nnot in the map (check they are installed):\n');
-  for (const u of unresolved.sort()) process.stderr.write(`  ${u}\n`);
-}