@plugjs/plug 0.1.4 → 0.2.0

package/extra/utils.ts

@@ -0,0 +1,168 @@
+/* eslint-disable no-console */
+import _childProcess from 'node:child_process'
+import _fs from 'node:fs'
+import _path from 'node:path'
+import _url from 'node:url'
+import _util from 'node:util'
+
+/* ========================================================================== *
+ * PRETTY COLORS                                                              *
+ * ========================================================================== */
+
+export const $rst = process.stdout.isTTY ? '\u001b[0m' : '' // reset all colors to default
+export const $und = process.stdout.isTTY ? '\u001b[4m' : '' // underline on
+export const $gry = process.stdout.isTTY ? '\u001b[38;5;240m' : '' // somewhat gray
+export const $blu = process.stdout.isTTY ? '\u001b[38;5;69m' : '' // brighter blue
+export const $wht = process.stdout.isTTY ? '\u001b[1;38;5;255m' : '' // full-bright white
+export const $tsk = process.stdout.isTTY ? '\u001b[38;5;141m' : '' // the color for tasks (purple)
+
+
+/* ========================================================================== *
+ * PACKAGE VERSION                                                            *
+ * ========================================================================== */
+
+export function version(): string {
+  const debug = _util.debuglog('plug:cli')
+
+  try {
+    const thisFile = _url.fileURLToPath(import.meta.url)
+    const packageFile = _path.resolve(thisFile, '..', '..', 'package.json')
+    const packageData = _fs.readFileSync(packageFile, 'utf-8')
+    return JSON.parse(packageData).version || '(unknown)'
+  } catch (error) {
+    debug('Error parsing version:', error)
+    return '(error)'
+  }
+}
+
+/* ========================================================================== *
+ * TS LOADER FORCE TYPE                                                       *
+ * ========================================================================== */
+
+function forceType(type: 'commonjs' | 'module'): void {
+  const debug = _util.debuglog('plug:cli')
+
+  const tsLoaderMarker = Symbol.for('plugjs:tsLoader')
+
+  if (!(tsLoaderMarker in globalThis)) {
+    throw new Error('TypeScript Loader not available')
+  }
+  debug(`Forcing type to "${type}"`)
+  ;(globalThis as any)[tsLoaderMarker] = type
+}
+
+
+/* ========================================================================== *
+ * FILES UTILITIES                                                            *
+ * ========================================================================== */
+
+/* Returns a boolean indicating whether the specified file exists or not */
+export function isFile(path: string): boolean {
+  try {
+    return _fs.statSync(path).isFile()
+  } catch (error) {
+    return false
+  }
+}
+
+/* Returns a boolean indicating whether the specified directory exists or not */
+export function isDirectory(path: string): boolean {
+  try {
+    return _fs.statSync(path).isDirectory()
+  } catch (error) {
+    return false
+  }
+}
+
+
+/* ========================================================================== *
+ * MAIN ENTRY POINT                                                           *
+ * ========================================================================== */
+export function main(callback: (args: string[]) => void | Promise<void>): void {
+  const debug = _util.debuglog('plug:cli')
+
+  /* Check for source maps and typescript support */
+  const sourceMapsEnabled = process.execArgv.indexOf('--enable-source-maps') >= 0
+
+  /* Check if our `ts-loader` loader is enabled */
+  const tsLoaderMarker = Symbol.for('plugjs:tsLoader')
+  const typeScriptEnabled = (globalThis as any)[tsLoaderMarker]
+
+  /* Some debugging if needed */
+  debug('SourceMaps enabled =', sourceMapsEnabled)
+  debug('TypeScript enabled =', typeScriptEnabled || false)
+
+  /* If both source maps and typescript are on, run! */
+  if (sourceMapsEnabled && typeScriptEnabled) {
+    const args = process.argv.slice(2).filter((arg: string): string | void => {
+      if (arg === '--force-esm') {
+        return forceType('module')
+      } else if (arg === '--force-cjs') {
+        return forceType('commonjs')
+      } else {
+        return arg
+      }
+    })
+
+
+    Promise.resolve().then(() => callback(args)).catch(console.error)
+  } else {
+    const script = _url.fileURLToPath(import.meta.url)
+
+    /* Fork out ourselves with new options */
+    const execArgv = [ ...process.execArgv ]
+
+    /* Enable source maps if not done already */
+    if (! sourceMapsEnabled) execArgv.push('--enable-source-maps')
+
+    /* Enable our ESM TypeScript loader if not done already */
+    if (! typeScriptEnabled) {
+      const directory = _path.dirname(script)
+      const extension = _path.extname(script) // .mts or .mjs
+      const loader = _path.resolve(directory, `ts-loader${extension}`)
+      execArgv.push(`--experimental-loader=${loader}`, '--no-warnings')
+    }
+
+    /*
+     * It seems that setting "type" as "module" in "package.json" creates some
+     * problems when the module is being imported from a "commonjs" one.
+     *
+     * TypeScript _incorrectly_ says (regardless of how we set up our conditional
+     * exports) that we must use dynamic imports:
+     *
+     *     Module '@plugjs/plug' cannot be imported using this construct. The
+     *     specifier only resolves to an ES module, which cannot be imported
+     *     synchronously. Use dynamic import instead.
+     *     TS(1471)
+     *
+     * So for now our only option is to leave "type" as "commonjs", and for those
+     * brave souls willing to force ESM irregardless of what's in "package.json",
+     * we allow the "--force-esm" option, and instruct `ts-loader` that the
+     * current directory (and subdirs) will transpile as ESM always.
+     */
+
+    /* Fork ourselves! */
+    const child = _childProcess.fork(script, [ ...process.argv.slice(2) ], {
+      stdio: [ 'inherit', 'inherit', 'inherit', 'ipc' ],
+      execArgv,
+    })
+
+    /* Monitor child process... */
+    child.on('error', (error) => {
+      console.log('Error respawning CLI', error)
+      process.exit(1)
+    })
+
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        console.log(`CLI process exited with signal ${signal}`)
+        process.exit(1)
+      } else if (typeof code !== 'number') {
+        console.log('CLI process failed for an unknown reason')
+        process.exit(1)
+      } else {
+        process.exit(code)
+      }
+    })
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plugjs/plug",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "commonjs",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -98,37 +98,27 @@
     }
   },
   "bin": {
-    "plug": "./extra/cli.mjs"
+    "plug": "./cli/plug.mjs",
+    "tsrun": "./cli/tsrun.mjs"
   },
-  "scripts": {
-    "bootstrap": "./bootstrap.sh",
-    "build": "./bootstrap.sh && ./extra/cli.mjs",
-    "dev": "./extra/cli.mjs -w ./src -w ./test"
-  },
-  "author": "",
-  "license": "ISC",
+  "author": "Juit Developers <developers@juit.com>",
+  "license": "Apache-2.0",
   "dependencies": {
     "@types/node": "<19",
-    "esbuild": "^0.15.18",
+    "esbuild": "^0.17.10",
     "picomatch": "^2.3.1",
-    "typescript": "^4.9.3"
+    "typescript": "^4.9.5"
   },
   "devDependencies": {
-    "@plugjs/cov8": "^0.1.2",
-    "@plugjs/eslint": "^0.1.2",
-    "@plugjs/eslint-plugin": "^0.1.1",
-    "@plugjs/jasmine": "^0.1.2",
-    "@plugjs/typescript": "^0.1.2",
     "@types/picomatch": "^2.3.0",
     "@types/yargs-parser": "^21.0.0",
-    "chai": "^4.3.7",
-    "chai-as-promised": "^7.1.1",
     "yargs-parser": "^21.1.1"
   },
   "files": [
     "*.md",
+    "cli/",
     "dist/",
-    "extra/*.mjs",
+    "extra/",
     "src/",
     "types/"
   ]

package/src/build.ts

@@ -80,7 +80,8 @@ function makeTask(
     const promise = runAsync(context, taskName, async () => {
       return await _def.call(build) || undefined
     }).then((result) => {
-      context.log.notice(`Success ${$ms(Date.now() - now)}`)
+      const level = taskName.startsWith('_') ? 'info' : 'notice'
+      context.log[level](`Success ${$ms(Date.now() - now)}`)
       return result
     }).catch((error) => {
       throw context.log.fail(`Failure ${$ms(Date.now() - now)}`, error)
@@ -102,8 +103,10 @@ function makeTask(
     return invoke(state, _name)
   }, { buildFile, tasks, props, invoke })
 
-  /* Assign the task name (nicely) and return it */
-  return Object.defineProperty(task, 'name', { value: _name })
+  /* Assign the task's marker and name and return it */
+  Object.defineProperty(task, taskMarker, { value: true })
+  Object.defineProperty(task, 'name', { value: _name })
+  return task
 }
 
 /* ========================================================================== *
@@ -124,14 +127,14 @@ export function build<
   /* Iterate through all definition extracting properties and tasks */
   for (const [ key, val ] of Object.entries(def)) {
     let len = 0
-    if (typeof val === 'string') {
+    if (isTask(val)) { // this goes first, tasks _are_ functions!
+      tasks[key] = val
+      len = key.length
+    } else if (typeof val === 'string') {
       props[key] = val
     } else if (typeof val === 'function') {
       tasks[key] = makeTask(buildFile, tasks, props, val, key)
       len = key.length
-    } else if (isTask(val)) {
-      tasks[key] = val
-      len = key.length
     }
 
     /* Update the logger's own "taskLength" for nice printing */

package/src/fork.ts

@@ -200,6 +200,7 @@ if ((process.argv[1] === requireFilename(__fileurl)) && (process.send)) {
         assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export a default constructor`)
       } else {
         Ctor = script[exportName]
+        if ((! Ctor) && (script.default)) Ctor = script.default[exportName]
         assert(typeof Ctor === 'function', `Script ${$p(scriptFile)} does not export "${exportName}"`)
       }
 

package/src/helpers.ts

@@ -1,6 +1,6 @@
+import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { mkdtempSync } from 'node:fs'
 
 import { assert, assertPromises } from './asserts'
 import { requireContext } from './async'

package/src/index.ts

@@ -6,6 +6,10 @@
 import type { Files } from './files'
 import type { Plug, PlugFunction } from './pipe'
 
+export { Files } from './files'
+export type { AbsolutePath } from './paths'
+export type { Plug, PlugFunction } from './pipe'
+
 /**
  * The {@link Pipe} interface defines a processing pipeline where multiple
  * {@link Plug}s can transform lists of {@link Files}.

package/src/plugs/edit.ts

@@ -2,12 +2,13 @@ import { readFile, writeFile } from '../fs'
 import { install } from '../pipe'
 
 import type { Files } from '../files'
+import type { AbsolutePath } from '../paths'
 import type { PipeParameters, Plug } from '../pipe'
 
 declare module '../index' {
   export interface Pipe {
     /** Edits the content of all files in a pipeline. */
-    edit(callback: (content: string) => string | void | Promise<string | void>): Pipe
+    edit(callback: (content: string, fileName: AbsolutePath) => string | void | Promise<string | void>): Pipe
   }
 }
 
@@ -17,7 +18,7 @@ declare module '../index' {
 
 /** Edits the content of all files in a pipeline. */
 install('edit', class Edit implements Plug<Files> {
-  private readonly _callback: (content: string) => string | void | Promise<string | void>
+  private readonly _callback: (content: string, fileName: AbsolutePath) => string | void | Promise<string | void>
 
   constructor(...args: PipeParameters<'edit'>) {
     this._callback = args[0]
@@ -26,7 +27,7 @@ install('edit', class Edit implements Plug<Files> {
   async pipe(files: Files): Promise<Files> {
     for (const file of files.absolutePaths()) {
       const data = await readFile(file, 'utf-8')
-      const edited = await this._callback(data)
+      const edited = await this._callback(data, file)
       if (edited !== undefined) await writeFile(file, edited, 'utf-8')
     }
     return files

package/src/plugs/esbuild.ts

@@ -65,7 +65,6 @@ install('esbuild', class ESBuild implements Plug<Files> {
       absWorkingDir,
       entryPoints,
       logLevel: 'silent',
-      watch: false,
     }
 
     if (options.format === 'cjs') {

package/src/plugs/exports.ts

@@ -0,0 +1,175 @@
+import { EOL } from 'node:os'
+import { sep } from 'node:path'
+
+import { Files } from '../files'
+import { readFile, writeFile } from '../fs'
+import { $p } from '../logging'
+import { assertRelativeChildPath, getAbsoluteParent } from '../paths'
+import { install } from '../pipe'
+
+import type { Context, PipeParameters, Plug } from '../pipe'
+
+/** Options for our `exports` plug. */
+export interface ExportsOptions {
+  /** The `package.json` file used as the input for processing */
+  packageJson?: string
+  /** The `package.json` file to be written including the matching exports */
+  outputPackageJson?: string
+  /** The extension for CommonJS modules (default: `.cjs` or `.js`) */
+  cjsExtension?: string
+  /** The extension for EcmaScript modules (default: `.mjs` or `.js`) */
+  esmExtension?: string
+}
+
+declare module '../index' {
+  export interface Pipe {
+    /** Include the files piped into this task as `exports` in `package.json` */
+    exports(options?: ExportsOptions): Pipe
+  }
+}
+
+/* ========================================================================== *
+ * INSTALLATION / IMPLEMENTATION                                              *
+ * ========================================================================== */
+
+type ExportsDeclaration = {
+  [ name in string ]? : {
+    [ type in 'require' | 'import' ]? : {
+      [ kind in 'types' | 'default' ]? : string
+    }
+  }
+}
+
+install('exports', class Exports implements Plug<Files> {
+  private readonly _packageJson: string
+  private readonly _outputPackageJson: string
+  private readonly _cjsExtension?: string
+  private readonly _esmExtension?: string
+
+  constructor(...args: PipeParameters<'exports'>) {
+    const options = args[0] || {}
+    const {
+      packageJson = 'package.json',
+      outputPackageJson = packageJson,
+      cjsExtension,
+      esmExtension,
+    } = options
+    this._packageJson = packageJson,
+    this._outputPackageJson = outputPackageJson
+    this._cjsExtension = cjsExtension
+    this._esmExtension = esmExtension
+  }
+
+  async pipe(files: Files, context: Context): Promise<Files> {
+    // read up our package.json, we need it to figure out the default `type`
+    const incomingFile = context.resolve(this._packageJson)
+    const incomingData = await readFile(incomingFile, 'utf8')
+    const packageData = JSON.parse(incomingData)
+
+    // exports must be relative to the _output_ package.json
+    const outgoingFile = context.resolve(this._outputPackageJson)
+    const outgoingDirectory = getAbsoluteParent(outgoingFile)
+
+    // type here determines the extension of commonjs or ecmascript modules
+    const type =
+      packageData.type === 'module' ? 'module' :
+      packageData.type === 'commonjs' ? 'commonjs' :
+      packageData.type == null ? 'commonjs' :
+      undefined
+    if (! type) context.log.fail(`Unknown module type "${packageData.type}" in ${$p(incomingFile)}`)
+
+    context.log.debug(`Package file ${$p(incomingFile)} declares module type "${type}"`)
+
+    const cjsExtension = this._cjsExtension || (type === 'commonjs' ? '.js' : '.cjs')
+    const esmExtension = this._esmExtension || (type === 'module' ? '.js' : '.mjs')
+
+    // reject when commonjs and ecmascript modules have the same extension
+    if (cjsExtension === esmExtension) {
+      context.log.fail(`CommonJS and EcmaScript modules both resolve to same extension "${cjsExtension}"`)
+    }
+
+    const exports: ExportsDeclaration = {}
+    function addExport(
+        name: string,
+        type: 'require' | 'import',
+        kind: 'types' | 'default',
+        file: string,
+    ): void {
+      if (! exports[name]) exports[name] = {}
+      if (! exports[name]![type]) exports[name]![type] = {}
+      exports[name]![type]![kind] = file
+    }
+
+    // all extensions to match in the incoming files
+    const exts = [ '.d.mts', '.d.cts', '.d.ts', cjsExtension, esmExtension ]
+
+    // look up all the files we were piped in
+    for (const [ name, absolute ] of files.pathMappings()) {
+      const relative = assertRelativeChildPath(outgoingDirectory, absolute)
+
+      for (const ext of exts) {
+        if (! relative.endsWith(ext)) continue
+
+        const base = `.${sep}${name.slice(0, -ext.length)}`
+        const exp = base.endsWith(`${sep}index`) ? base.slice(0, -6) : base
+
+        switch (ext) {
+          case cjsExtension:
+            addExport(exp, 'require', 'default', `.${sep}${relative}`)
+            break
+          case esmExtension:
+            addExport(exp, 'import', 'default', `.${sep}${relative}`)
+            break
+          case '.d.cts':
+            addExport(exp, 'require', 'types', `.${sep}${relative}`)
+            break
+          case '.d.mts':
+            addExport(exp, 'import', 'types', `.${sep}${relative}`)
+            break
+          case '.d.ts':
+            addExport(exp, 'require', 'types', `.${sep}${relative}`)
+            addExport(exp, 'import', 'types', `.${sep}${relative}`)
+            break
+        }
+      }
+    }
+
+    // if we have a "." export, inject the "main", "module" and "types" fields
+    if ('.' in exports) {
+      const rootExport = exports['.']
+      packageData['main'] = rootExport?.require?.default
+      packageData['module'] = rootExport?.import?.default
+      packageData['types'] = packageData['type'] === 'module' ?
+        rootExport?.import?.types : rootExport?.require?.types
+    }
+
+    // correctly order the exports record (e.g. types comes before default)
+    packageData['exports'] = Object.keys(exports).sort().reduce((obj, name) => {
+      const current = exports[name]
+      if (! current) return obj
+
+      // json serialization will scrub all undefined... here we export the types
+      // only if the "default" export is available, or we scrub the whole thing!
+      obj[name] = current.require?.default || current.import?.default ? {
+        require: current.require?.default ? {
+          types: current.require.types || undefined,
+          default: current.require.default || undefined,
+        } : undefined,
+        import: current.import?.default ? {
+          types: current.import.types || undefined,
+          default: current.import.default || undefined,
+        } : undefined,
+      } : undefined
+
+      return obj
+    }, {} as ExportsDeclaration)
+
+    // convert back our package data into a json and write it
+    const outgoingData = JSON.stringify(packageData, null, 2)
+    context.log.info(`Writing new ${$p(outgoingFile)}`, outgoingData)
+    await writeFile(outgoingFile, outgoingData + EOL, 'utf8')
+
+    // return a `Files` instance with our `package.json` in there
+    return Files.builder(getAbsoluteParent(outgoingFile)).add(outgoingFile).build()
+  }
+})

package/src/plugs.ts

@@ -3,5 +3,6 @@ export * from './plugs/debug'
 export * from './plugs/edit'
 export * from './plugs/esbuild'
 export * from './plugs/exec'
+export * from './plugs/exports'
 export * from './plugs/filter'
 export * from './plugs/rmf'

package/types/plugjs.d.ts

@@ -1,5 +1,3 @@
-/// <reference no-default-lib="true"/>
-
 /**
  * A pseudo-variable replaced by `ESBuild` resolving to either `__filename`
  * in CJS modules, or to `import.meta.url` in ESM modules.