mappel 0.0.0-name-check.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibrahima Toure
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,34 @@
-placeholder
+# mappel
+
+This package builds an import map from what a workspace actually imports. It reads package manifests and import statements, and writes JSON. It does not bundle or build anything.
+
+The browser resolves a bare specifier only through an import map and never reads package.json. Every transitive subpath has to be listed — including the ones a package reaches through its own dependencies. Written by hand, that list is wrong within a release.
+
+It resolves each specifier through the package's own exports map — nested conditions, wildcards, and the form with no "." key — then walks the files it finds for more specifiers. It reports what it could not resolve rather than emitting a map that fails in the browser.
+
+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                                  # 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
+// 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,6 +1,36 @@
 {
   "name": "mappel",
-  "version": "0.0.0-name-check.0",
-  "description": "placeholder",
-  "license": "MIT"
+  "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/mappel.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./resolve": "./src/resolve.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "version": "changeset version",
+    "release": "npm test && changeset publish"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bambiste/mappel.git"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.1"
+  }
 }

package/src/index.mjs

@@ -0,0 +1,206 @@
+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';
+
+const IMPORT_RE = /(?:from|import)\s*["']([^"']+)["']/g;
+
+function scanImports(file) {
+  let src;
+  try {
+    src = readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const [, spec] of src.matchAll(IMPORT_RE)) {
+    // Doc comments quote specifiers too; a real one has no whitespace or `${}`.
+    if (/\s|\$\{/.test(spec)) continue;
+    found.push(spec);
+  }
+  return found;
+}
+
+/**
+ * Walk from a set of specifiers to every bare specifier reachable from them,
+ * mapped to a url a browser can fetch.
+ */
+export function collect(specifiers, 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();
+  const visited = new Set();
+
+  const urlFor = (name, dir, file) => {
+    const clean = file.replace(/^\.\//, '');
+    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) => {
+    if (visited.has(spec)) return;
+    visited.add(spec);
+
+    const { pkg, sub } = splitSpecifier(spec);
+    const dir = packageDir(root, pkg, workspaces);
+    if (!dir) return void unresolved.add(spec);
+
+    const file = resolveExport(dir, sub);
+    if (!file) return void unresolved.add(spec);
+
+    if (spec.endsWith('.css')) {
+      stylesheets.add(urlFor(pkg, dir, file));
+      // A browser cannot import a stylesheet as a module. The loader sibling adds
+      // it as a <link>, so importing a component still brings its styles.
+      imports[spec] = css === 'loader' ? urlFor(pkg, dir, file + '.js') : 'data:text/javascript,';
+      return;
+    }
+
+    imports[spec] = urlFor(pkg, dir, file);
+
+    const entry = join(dir, file.replace(/^\.\//, ''));
+    const seen = new Set();
+    const stack = [entry];
+    while (stack.length) {
+      const current = stack.pop();
+      if (seen.has(current) || !existsSync(current)) continue;
+      seen.add(current);
+      for (const nested of scanImports(current)) {
+        if (nested.startsWith('.')) {
+          const next = normalize(join(dirname(current), nested));
+          stack.push(existsSync(next) ? next : next + '.js');
+        } else if (!nested.startsWith('node:')) {
+          add(nested);
+        }
+      }
+    }
+  };
+
+  for (const spec of specifiers) add(spec);
+  return { imports, stylesheets: [...stylesheets], unresolved: [...unresolved] };
+}
+
+const sorted = (obj) =>
+  Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+
+/**
+ * Build one named layer. `excludes` names other layers whose entries this one
+ * leaves out, so a page loading both is not handed the same entry twice.
+ */
+export function buildLayer(name, config, options) {
+  const layer = config.layers[name];
+  if (!layer) throw new Error(`[import-map] no layer named "${name}"`);
+
+  const resolveList = (list) => (typeof list === 'function' ? list(helpers(options)) : list);
+  const mine = collect(resolveList(layer.packages), { ...options, ...config.options });
+
+  const skip = new Set();
+  for (const other of layer.excludes ?? []) {
+    const theirs = collect(resolveList(config.layers[other].packages), { ...options, ...config.options });
+    for (const key of Object.keys(theirs.imports)) skip.add(key);
+  }
+
+  const imports = {};
+  for (const [key, value] of Object.entries(mine.imports)) {
+    if (skip.has(key)) continue;
+    if ((layer.excludePrefixes ?? []).some((p) => key.startsWith(p))) continue;
+    imports[key] = value;
+  }
+  return { imports: sorted(imports), stylesheets: mine.stylesheets, unresolved: mine.unresolved };
+}
+
+function helpers(options) {
+  return {
+    subpathsOf: (name) => subpathsOf(options.root, name, options.workspaces),
+    root: options.root,
+  };
+}
+
+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/src/resolve.mjs

@@ -0,0 +1,101 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const manifests = new Map();
+
+export function manifest(dir) {
+  if (!manifests.has(dir)) {
+    manifests.set(dir, JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')));
+  }
+  return manifests.get(dir);
+}
+
+export function splitSpecifier(spec) {
+  const parts = spec.split('/');
+  const pkg = spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+  const sub = spec.length > pkg.length ? '.' + spec.slice(pkg.length) : '.';
+  return { pkg, sub };
+}
+
+/**
+ * Where a package lives. A workspace folder wins over an installed copy, and
+ * pnpm's store is searched last: it keeps the real files under
+ * .pnpm/<name>@<version>/node_modules/<name>, and a package only appears at the
+ * top level when something depends on it directly.
+ */
+export function packageDir(root, name, workspaces = ['packages']) {
+  for (const dir of workspaces) {
+    const local = join(root, dir, name.split('/').pop());
+    if (existsSync(join(local, 'package.json'))) {
+      try {
+        if (manifest(local).name === name) return local;
+      } catch {
+        /* not a manifest we can read */
+      }
+    }
+  }
+  const installed = join(root, 'node_modules', name);
+  if (existsSync(join(installed, 'package.json'))) return installed;
+
+  const store = join(root, 'node_modules', '.pnpm');
+  if (existsSync(store)) {
+    const prefix = name.replace('/', '+') + '@';
+    for (const dir of readdirSync(store).filter((d) => d.startsWith(prefix)).sort().reverse()) {
+      const real = join(store, dir, 'node_modules', name);
+      if (existsSync(join(real, 'package.json'))) return real;
+    }
+  }
+  return null;
+}
+
+/** Conditions nest, and `{ import: { types, default } }` is as common as a string. */
+export function pickTarget(entry) {
+  if (typeof entry === 'string') return entry;
+  if (Array.isArray(entry)) {
+    for (const alt of entry) {
+      const found = pickTarget(alt);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (entry && typeof entry === 'object') {
+    for (const key of ['browser', 'import', 'default', 'require']) {
+      if (entry[key] === undefined) continue;
+      const found = pickTarget(entry[key]);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+export function resolveExport(dir, sub) {
+  const m = manifest(dir);
+  const exp = m.exports;
+  if (!exp) return sub === '.' ? m.module || m.main || null : null;
+  // No key starting with '.' means `exports` is a bare set of conditions that IS
+  // the root entry — `{ import, require, types }` — rather than a subpath map.
+  if (!Object.keys(exp).some((k) => k.startsWith('.'))) {
+    return sub === '.' ? pickTarget(exp) : null;
+  }
+  if (exp[sub] !== undefined) return pickTarget(exp[sub]);
+  for (const [pattern, entry] of Object.entries(exp)) {
+    if (!pattern.includes('*')) continue;
+    const [before, after] = pattern.split('*');
+    if (sub.startsWith(before) && sub.endsWith(after)) {
+      const filled = sub.slice(before.length, sub.length - (after.length || 0));
+      const target = pickTarget(entry);
+      if (target) return target.replace('*', filled);
+    }
+  }
+  return null;
+}
+
+/** A package with no root export still has subpaths worth mapping. */
+export function subpathsOf(root, name, workspaces) {
+  const dir = packageDir(root, name, workspaces);
+  if (!dir) return [];
+  const exp = manifest(dir).exports || {};
+  return Object.keys(exp)
+    .filter((k) => k.startsWith('./') && k !== './package.json')
+    .map((k) => name + k.slice(1));
+}