mappel 0.0.0-name-check.0 → 0.1.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,26 @@
-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 --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
+```
+
+```js
+// importmap.config.mjs
+export default {
+  layers: {
+    base: { packages: ['@scope/core', '@scope/dom'] },
+    extra: { packages: ['@scope/extra'], excludes: ['base'] },
+  },
+};
+```

package/bin/import-map.mjs

@@ -0,0 +1,92 @@
+#!/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`);
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "mappel",
-  "version": "0.0.0-name-check.0",
-  "description": "placeholder",
-  "license": "MIT"
+  "version": "0.1.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"
+  },
+  "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,120 @@
+import { readFileSync, existsSync } 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 } = options;
+  const imports = {};
+  const stylesheets = new Set();
+  const unresolved = new Set();
+  const visited = new Set();
+
+  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}`;
+  };
+
+  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 };

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));
+}