bare-stow 0.1.8 → 0.2.0

package/index.js

@@ -1,86 +1,101 @@
 const path = require('path')
-const { fileURLToPath } = require('url')
 const pack = require('bare-pack')
 const id = require('bare-bundle-id')
-const strip = require('bare-type-stripper')
-const { resolve } = require('bare-module-traverse')
-const lex = require('bare-module-lexer')
 const fs = require('./lib/fs')
+const assets = require('./lib/assets')
 const shim = require('./lib/shim')
-const harness = require('./lib/target')
-const rpc = require('./lib/rpc')
+const graph = require('./lib/graph')
+const rpcs = require('./lib/rpc')
+const { select } = require('./lib/provider')
 
-module.exports = async function* stow(entry, target, out, opts = {}) {
+module.exports = exports = async function* stow(entry, target, out, opts = {}) {
   if (!target) throw new Error("'target' is required")
   if (!out) throw new Error("'out' is required")
 
-  let { client, server, base, hosts, resolveTarget, resolveRPC, ...packOpts } = opts
-
-  const t = harness(target, resolveTarget)
-
-  const targetName = typeof target === 'string' ? target : t.name
+  let {
+    language,
+    languageOptions,
+    targetOptions,
+    client,
+    server,
+    base,
+    hosts,
+    resolveTarget,
+    resolveRPC,
+    resolveLanguage,
+    ...packOpts
+  } = opts
 
   entry = await fs.resolveModule(new URL(entry))
   out = new URL(out)
 
-  // The target may pin a module system; otherwise it follows the output path.
-  const module = t.module || (await resolveModule(out))
+  if (!out.pathname.endsWith('/')) out.pathname += '/'
 
-  if (hosts) {
-    for (const host of hosts) {
-      if (!t.hosts.includes(host)) {
-        throw new Error(`Host '${host}' is not supported by target '${targetName}'`)
-      }
+  const resolved = graph.providers(target, {
+    language,
+    languageOptions,
+    targetOptions,
+    hosts,
+    resolveTarget,
+    resolveLanguage
+  })
+
+  const { harness, options } = resolved
+
+  target = resolved.target
+  language = resolved.language
+  hosts = resolved.hosts
+
+  if (client) client = select('RPC library', rpcs(client, resolveRPC), language.name)
+  if (server) server = rpcs(server, resolveRPC)
+
+  const layout = language.layout(out, options)
+
+  const bundleURL = new URL('index' + target.extension, layout.artifacts ?? layout.harness)
+
+  // Linked bundles leave their assets out, as files that the runtime loads from
+  // next to the bundle or from the application.
+  const resources = target.linked && target.linking === 'app' ? assets.app : null
+  const name = resources ?? 'index'
+
+  if (client) {
+    client = {
+      url: language.sibling(layout.harness, 'client'),
+      ...client.generate({ role: 'client', options })
     }
-  } else {
-    hosts = t.hosts
   }
 
-  const shimURL = shim.url(new URL('./', entry))
-
-  // The server only contributes runtime wiring to the shim; the shim is not a
-  // typed, host-facing module so it has no declaration artifact.
-  const serverSetup = server
-    ? fragment(
-        rpc(server, resolveRPC).generate({
-          ipc: 'ipc',
-          rpc: 'rpc',
-          module: 'esm',
-          role: 'server'
-        }),
-        null
-      )
-    : null
+  const files = [
+    {
+      url: layout.harness,
+      ...harness.generate({
+        bundle: language.reference(layout.harness, bundleURL),
+        client: client && language.reference(layout.harness, client.url),
+        resources,
+        options
+      })
+    }
+  ]
 
-  const shimSource = shim(entry, shimURL, { server: serverSetup })
+  if (client) files.push(client)
 
-  const readModule = wrapReadModule(fs.readModule, shimURL, shimSource)
+  const main = shim(entry, target.isolation, server)
 
-  const bundleURL = siblingURL(out, t.extension)
-  const bundleSpecifier = relativeSpecifier(out, bundleURL)
+  const readModule = graph.readModule(main.modules)
 
   const offloaded = []
 
   let writeFile
 
-  if (isOffloadEnabled(t.offload)) writeFile = collectOffloaded(offloaded)
+  if (isOffloadEnabled(target.offload)) writeFile = collectOffloaded(offloaded)
+
+  const traversal = graph.traversal(packOpts, hosts)
 
   // The base of the bundle depends on where its modules live, so the graph is
   // packed unbased and unmounted once that is known.
   let bundle = await pack(
-    shimURL,
-    {
-      ...packOpts,
-      resolve: resolve.bare,
-      aliases: {
-        '.ts': '.js',
-        '.mts': '.mjs',
-        '.cts': '.cjs'
-      },
-      hosts,
-      linked: t.linked,
-      offload: t.offload
-    },
+    main.url,
+    { ...traversal, linked: target.linked, offload: target.offload },
     readModule,
     fs.listPrefix,
     fs.resolveModule,
@@ -91,50 +106,70 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
 
   bundle = rerootOffloaded(bundle.unmount(base), base, bundleURL, offloaded)
 
+  let unpacked = []
+
+  if (target.linked) {
+    const result = await assets.unpack(bundle, base, name)
+
+    bundle = result.bundle
+
+    // Assets left to the application are written by `link()` instead.
+    if (resources === null) unpacked = result.assets
+  }
+
   bundle.id = id(bundle).toString('hex')
 
-  // The client contributes both runtime wiring (spliced into the harness) and a
-  // type expression (spliced into the harness declaration), so it is resolved
-  // into both channels before handing it to the target.
-  let clientSetup = null
+  // The manifest lists the offloaded files only once it's known there are any.
+  const artifacts = offloaded.length > 0 ? [bundleURL, offloadURL(bundleURL)] : [bundleURL]
 
-  if (client) {
-    const artifacts = rpc(client, resolveRPC).generate({
-      ipc: 'ipc',
-      rpc: 'rpc',
-      role: 'client',
-      module
-    })
+  if (unpacked.length > 0) {
+    artifacts.push(new URL(name + '/', bundleURL), new URL(name + '.assets', bundleURL))
+  }
+
+  const addons = []
+
+  // Targets that leave linking to the application use `link()` instead.
+  if (target.linked && target.linking === 'package') {
+    if (!layout.addons) {
+      throw new Error(`Language '${language.name}' does not support linked addons`)
+    }
 
-    clientSetup = {
-      source: fragment(artifacts, null),
-      type: fragment(artifacts, '.d.ts')
+    for await (const url of graph.link([main.url], layout.addons, traversal, readModule)) {
+      addons.push(url)
+      yield { url }
     }
   }
 
-  const artifacts = t.generate({
-    bundleSpecifier,
-    ipc: 'ipc',
-    rpc: 'rpc',
-    module,
-    client: clientSetup
+  files.push({
+    url: layout.manifest,
+    source: language.manifest({
+      name: layout.name,
+      dependencies: Object.assign({}, ...files.map((file) => file.dependencies)),
+      options,
+      hosts,
+      artifacts: artifacts.map((url) => language.reference(layout.manifest, url)),
+      addons: addons.map((url) => language.reference(layout.manifest, url))
+    })
   })
 
-  for (const artifact of artifacts) {
-    if (!artifact.extension) await assertImportsResolve(artifact.source, out)
-  }
+  for (const file of files) {
+    await fs.writeFile(file.url, file.source)
+    yield { url: file.url }
 
-  // The first artifact is the harness written to `out`; any further artifacts
-  // are siblings named after `out` with the artifact's own extension.
-  for (const artifact of artifacts) {
-    const url = artifact.extension ? siblingURL(out, artifact.extension) : out
+    if (file.types) {
+      const typesURL = language.types(file.url)
 
-    await fs.writeFile(url, artifact.source)
-    yield { url }
+      await fs.writeFile(typesURL, file.types)
+      yield { url: typesURL }
+    }
   }
 
-  await fs.writeFile(bundleURL, encodeBundle(bundle, t.format, t.encoding ?? 'utf8'))
-  yield { url: bundleURL }
+  await fs.writeFile(bundleURL, encodeBundle(bundle, target.format, target.encoding ?? 'utf8'))
+  yield { url: bundleURL, base }
+
+  if (unpacked.length > 0) {
+    for await (const url of assets.write(new URL('./', bundleURL), name, unpacked)) yield { url }
+  }
 
   // Offloaded files are collected in the order their reads complete, so they
   // are sorted to keep the output stable.
@@ -146,8 +181,8 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
   }
 }
 
-function resolveBase(base, graph) {
-  const modules = [...graph.keys()].map((href) => new URL(href))
+function resolveBase(base, bundle) {
+  const modules = [...bundle.keys()].map((href) => new URL(href))
 
   if (base) {
     base = new URL(base)
@@ -191,20 +226,6 @@ function isOffloadEnabled(offload) {
   return false
 }
 
-function wrapReadModule(readModule, shimURL, shimSource) {
-  return async function (url) {
-    if (url.href === shimURL.href) return shimSource
-
-    const source = await readModule(url)
-
-    if (source === null) return null
-
-    if (/\.(c|m)?ts$/.test(url.pathname)) return strip(source)
-
-    return source
-  }
-}
-
 function collectOffloaded(sink) {
   return function writeFile(url, source) {
     sink.push({ url, source })
@@ -217,11 +238,15 @@ function collectOffloaded(sink) {
 // next to the harness, as a mirrored `node_modules` beside the harness would
 // shadow the packages it imports. Their resolutions are rewritten to point into
 // that directory, along with the directories that hold them.
+function offloadURL(bundleURL) {
+  return new URL(path.basename(bundleURL.pathname) + '.d/', bundleURL)
+}
+
 function rerootOffloaded(bundle, base, bundleURL, offloaded) {
   if (offloaded.length === 0) return bundle
 
-  const name = path.basename(bundleURL.pathname) + '.d'
-  const dir = new URL(name + '/', bundleURL)
+  const dir = offloadURL(bundleURL)
+  const name = path.basename(dir.pathname)
   const rewrites = new Map()
 
   for (const file of offloaded) {
@@ -288,107 +313,6 @@ function isTerminator(input) {
   return input === '' || input.endsWith('/') || input.endsWith(':')
 }
 
-async function assertImportsResolve(source, out) {
-  for (const entry of lex(source).imports) {
-    const { specifier } = entry
-
-    if (specifier.startsWith('.') || specifier.startsWith('/')) continue
-
-    if (await resolves(entry, out)) continue
-
-    throw new Error(
-      `Harness '${fileURLToPath(out)}' imports '${specifier}', which the package containing it does not depend on`
-    )
-  }
-}
-
-async function resolves(entry, parentURL) {
-  const resolver = resolve.bare(entry, parentURL)
-
-  let next = resolver.next()
-
-  while (next.done !== true) {
-    const value = next.value
-
-    if (value.package) {
-      const source = await fs.readModule(value.package)
-
-      next = resolver.next(source === null ? null : JSON.parse(source))
-    } else {
-      const exists = await fs.isFile(value.resolution)
-
-      if (exists) return true
-
-      next = resolver.next(false)
-    }
-  }
-
-  return false
-}
-
-async function resolveModule(out) {
-  switch (path.extname(out.pathname)) {
-    case '.mjs':
-      return 'esm'
-    case '.cjs':
-      return 'cjs'
-  }
-
-  // For an ambiguous extension (e.g. '.js') the module system follows the
-  // `type` of the closest enclosing `package.json`, defaulting to CommonJS.
-  return (await packageType(new URL('./', out))) === 'module' ? 'esm' : 'cjs'
-}
-
-async function packageType(dir) {
-  while (true) {
-    let source = null
-
-    try {
-      source = await fs.readFile(new URL('package.json', dir))
-    } catch {
-      // No `package.json` in this directory; keep searching upwards.
-    }
-
-    if (source !== null) return JSON.parse(source).type ?? null
-
-    const parent = new URL('../', dir)
-
-    if (parent.pathname === dir.pathname) return null
-
-    dir = parent
-  }
-}
-
-function siblingURL(out, extension) {
-  const dir = new URL('./', out)
-  const base = path.basename(out.pathname, path.extname(out.pathname))
-
-  return new URL(base + extension, dir)
-}
-
-function fragment(artifacts, extension) {
-  for (const artifact of artifacts) {
-    if ((artifact.extension ?? null) === extension) return artifact.source
-  }
-
-  return null
-}
-
-function relativeSpecifier(from, to) {
-  if (from.protocol === 'file:' && to.protocol === 'file:') {
-    const fromDir = path.dirname(fileURLToPath(from))
-    const toPath = fileURLToPath(to)
-
-    let relative = path.relative(fromDir, toPath).split(path.sep).join('/')
-
-    if (!relative.startsWith('.')) relative = './' + relative
-
-    return relative
-  }
-
-  return to.href
-}
-
 function encodeBundle(bundle, format, encoding) {
   const data = bundle.toBuffer()
 
@@ -405,3 +329,7 @@ function encodeBundle(bundle, format, encoding) {
       throw new Error(`Unknown format '${format}'`)
   }
 }
+
+exports.link = require('./lib/link')
+
+exports.resources = assets.app

package/lib/assets.js

@@ -0,0 +1,54 @@
+const unpack = require('bare-unpack')
+const fs = require('./fs')
+
+// The assets of bundles linked by the application share one directory, named
+// after the bundle that Bare Kit starts them as.
+exports.app = 'bare-stow'
+
+// Assets are laid out the way Bare Kit expects: the assets of `<name>.bundle`
+// live in `<name>/`, listed in `<name>.assets` for platforms that extract them.
+exports.unpack = async function (bundle, base, name) {
+  const assets = []
+
+  bundle = await unpack(bundle, { files: false, assets: true }, async (key) => {
+    const relative = await exports.path(new URL('.' + key, base))
+
+    assets.push({ path: relative, source: bundle.read(key) })
+
+    return '/../' + name + '/' + relative
+  })
+
+  return { bundle, assets }
+}
+
+// Assets of dependencies keep their path from `node_modules`, and others their
+// path within their package, so that every bundle places an asset alike.
+exports.path = async function (url) {
+  const nm = url.pathname.indexOf('/node_modules/')
+
+  if (nm >= 0) return url.pathname.slice(nm + 1)
+
+  for (let dir = new URL('./', url); ; dir = new URL('../', dir)) {
+    if (await fs.isFile(new URL('package.json', dir))) {
+      return url.pathname.slice(dir.pathname.length)
+    }
+
+    if (dir.pathname === '/') throw new Error(`Asset '${url.href}' is not part of a package`)
+  }
+}
+
+exports.write = async function* (dir, name, assets) {
+  assets = [...assets].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+
+  for (const asset of assets) {
+    const url = new URL(name + '/' + asset.path, dir)
+
+    await fs.writeFile(url, asset.source)
+    yield url
+  }
+
+  const listing = new URL(name + '.assets', dir)
+
+  await fs.writeFile(listing, assets.map((asset) => '/' + asset.path + '\n').join(''))
+  yield listing
+}

package/lib/fs.js

@@ -43,7 +43,7 @@ exports.readModule = async function readModule(url) {
   }
 }
 
-function isFile(url) {
+exports.isFile = function isFile(url) {
   return new Promise((resolve) => {
     fs.stat(fileURLToPath(url), (err, stat) => {
       resolve(err === null && stat.isFile())
@@ -60,7 +60,7 @@ function isDir(url) {
 }
 
 exports.listPrefix = async function* listPrefix(url) {
-  if (await isFile(url)) return yield url
+  if (await exports.isFile(url)) return yield url
 
   if (url.pathname[url.pathname.length - 1] !== '/') {
     url.pathname += '/'
@@ -77,6 +77,4 @@ exports.listPrefix = async function* listPrefix(url) {
   }
 }
 
-exports.isFile = isFile
-
 exports.resolveModule = require('bare-pack/fs').resolveModule

package/lib/graph.js

@@ -0,0 +1,96 @@
+const { fileURLToPath, pathToFileURL } = require('url')
+const bareLink = require('bare-link')
+const strip = require('bare-type-stripper')
+const { resolve } = require('bare-module-traverse')
+const fs = require('./fs')
+const targets = require('./target')
+const languages = require('./language')
+const { select } = require('./provider')
+
+exports.providers = function providers(target, opts = {}) {
+  let {
+    language = 'javascript',
+    languageOptions,
+    targetOptions,
+    hosts,
+    resolveTarget,
+    resolveLanguage
+  } = opts
+
+  target = targets(target, resolveTarget)
+  language = languages(language, resolveLanguage)
+
+  const harness = select('Target', target, language.name)
+
+  // A target may pin options that it can't do without, overriding those given.
+  const options = { ...language.options(languageOptions), ...harness.options }
+
+  targetOptions = targets.options(target, targetOptions)
+
+  target = targets.resolve(target, { language: language.name, options, targetOptions })
+
+  hosts = resolveHosts(hosts, target.hosts, target.name)
+
+  return { target, language, harness, options, targetOptions, hosts }
+}
+
+function resolveHosts(hosts, supported, name) {
+  if (!hosts) return supported
+
+  for (const host of hosts) {
+    if (!supported.includes(host)) {
+      throw new Error(`Host '${host}' is not supported by target '${name}'`)
+    }
+  }
+
+  return hosts
+}
+
+// The graph is traversed the same way when packing it as when linking its
+// addons.
+exports.traversal = function traversal(opts, hosts) {
+  return {
+    ...opts,
+    resolve: resolve.bare,
+    aliases: {
+      '.ts': '.js',
+      '.mts': '.mjs',
+      '.cts': '.cjs'
+    },
+    hosts
+  }
+}
+
+exports.readModule = function readModule(modules) {
+  return async function (url) {
+    if (modules.has(url.href)) return modules.get(url.href)
+
+    const source = await fs.readModule(url)
+
+    if (source === null) return null
+
+    if (/\.(c|m)?ts$/.test(url.pathname)) return strip(source)
+
+    return source
+  }
+}
+
+// The layout must not depend on the hosts, as Swift packages only accept
+// XCFrameworks. Resources linked outside of the directory are intermediate.
+exports.link = async function* link(entries, dir, traversal, readModule) {
+  for await (const resource of bareLink(
+    entries.map((url) => fileURLToPath(url)),
+    {
+      ...traversal,
+      out: fileURLToPath(dir),
+      alwaysMultiHost: true,
+      readModule,
+      listPrefix: fs.listPrefix,
+      resolveModule: fs.resolveModule
+    }
+  )) {
+    const url = pathToFileURL(resource)
+
+    if (url.href.startsWith(dir.href)) yield url
+  }
+}

package/lib/language/javascript.js

@@ -0,0 +1,74 @@
+const path = require('path')
+const { fileURLToPath } = require('url')
+
+exports.name = 'javascript'
+
+const MODULES = ['esm', 'cjs']
+
+exports.options = function options(given = {}) {
+  const { module = 'esm', ...unknown } = given
+
+  for (const name of Object.keys(unknown)) {
+    throw new Error(`Unknown option '${name}' for language 'javascript'`)
+  }
+
+  if (!MODULES.includes(module)) {
+    throw new Error(`Option 'module' must be one of ${MODULES.join(', ')}, got '${module}'`)
+  }
+
+  return { module }
+}
+
+exports.layout = function layout(out) {
+  const name = path.posix.basename(out.pathname)
+
+  if (!/^[a-z0-9~-][a-z0-9._~-]*$/.test(name)) {
+    throw new Error(`'${name}' is not a valid package name`)
+  }
+
+  return {
+    harness: new URL('index.js', out),
+    name,
+    manifest: new URL('package.json', out)
+  }
+}
+
+exports.sibling = function sibling(url, name) {
+  return new URL(`${name}.js`, url)
+}
+
+exports.types = function types(url) {
+  return new URL(path.posix.basename(url.pathname, '.js') + '.d.ts', url)
+}
+
+exports.reference = function reference(from, to) {
+  if (from.protocol === 'file:' && to.protocol === 'file:') {
+    const fromDir = path.dirname(fileURLToPath(from))
+    const toPath = fileURLToPath(to)
+
+    let relative = path.relative(fromDir, toPath).split(path.sep).join('/')
+
+    if (!relative.startsWith('.')) relative = './' + relative
+
+    return relative
+  }
+
+  return to.href
+}
+
+exports.manifest = function manifest({ name, dependencies, options }) {
+  const pkg = {
+    name,
+    private: true,
+    type: options.module === 'esm' ? 'module' : 'commonjs',
+    exports: {
+      '.': {
+        types: './index.d.ts',
+        default: './index.js'
+      }
+    },
+    dependencies
+  }
+
+  return JSON.stringify(pkg, null, 2) + '\n'
+}