mappel 0.1.0 → 0.2.0

package/README.md

@@ -9,15 +9,23 @@ 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.
 
 ```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 --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
   layers: {
     base: { packages: ['@scope/core', '@scope/dom'] },
     extra: { packages: ['@scope/extra'], excludes: ['base'] },

package/bin/mappel.mjs

@@ -0,0 +1,124 @@
+#!/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
+//
+// With no arguments it finds mappel.config.mjs by walking up from the current
+// directory, so a package's build script is just `mappel`.
+
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { buildLayer, writeAll, 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);
+
+if (!layerName && !splitInto) {
+  const out = resolvePath(flag('out', config.out ? join(base, config.out) : join(base, 'dist')));
+  const written = writeAll(config, { ...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;
+    writeFileSync(join(dir, name.split('/').pop() + '.json'), JSON.stringify({ imports: one.imports }, null, 2) + '\n');
+    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) {
+  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.2.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,78 @@ function helpers(options) {
 }
 
 export { subpathsOf, packageDir, resolveExport };
+
+/**
+ * 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`);
+    writeFileSync(file, JSON.stringify({ imports }, null, 2) + '\n');
+    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`);
+    writeFileSync(
+      file,
+      JSON.stringify(
+        { imports: Object.fromEntries(Object.entries(imports).sort(([a], [b]) => a.localeCompare(b))) },
+        null,
+        2,
+      ) + '\n',
+    );
+    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;
+      writeFileSync(
+        join(dir, name.split('/').pop() + '.json'),
+        JSON.stringify({ imports: one.imports }, null, 2) + '\n',
+      );
+      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`);
-}