@plugjs/plug 0.1.0 → 0.1.1

package/src/build.ts

@@ -0,0 +1,179 @@
+import { assert } from './asserts'
+import { runAsync } from './async'
+import { $ms, $t, getLogger, log, logOptions } from './logging'
+import { Context, ContextPromises, PipeImpl } from './pipe'
+import { findCaller } from './utils/caller'
+import { parseOptions } from './utils/options'
+
+import type { Pipe } from './index'
+import type { AbsolutePath } from './paths'
+import type {
+  Build,
+  BuildDef,
+  Props,
+  Result,
+  State,
+  Task,
+  TaskDef,
+  Tasks,
+  ThisBuild,
+} from './types'
+
+/* ========================================================================== *
+ * TASK                                                                       *
+ * ========================================================================== */
+
+class TaskImpl implements Task {
+  constructor(
+      public readonly buildFile: AbsolutePath,
+      public readonly tasks: Tasks,
+      public readonly props: Props,
+      private readonly _def: TaskDef,
+  ) {}
+
+  invoke(state: State, taskName: string): Promise<Result> {
+    assert(! state.stack.includes(this), `Recursion detected calling ${$t(taskName)}`)
+
+    /* Check cache */
+    const cached = state.cache.get(this)
+    if (cached) return cached
+
+    /* Create new substate merging sibling tasks/props and adding this to the stack */
+    const props: Record<string, string> = Object.assign({}, this.props, state.props)
+    const tasks: Record<string, Task> = Object.assign({}, this.tasks, state.tasks)
+    const stack = [ ...state.stack, this ]
+    const cache = state.cache
+
+    /* Create run context and build */
+    const context = new Context(this.buildFile, taskName)
+
+    const build = new Proxy({}, {
+      get(_: any, name: string): void | string | (() => Pipe) {
+        // Tasks first, props might come also from environment
+        if (name in tasks) {
+          return (): Pipe => {
+            const state = { stack, cache, tasks, props }
+            const promise = tasks[name]!.invoke(state, name)
+            return new PipeImpl(context, promise)
+          }
+        } else if (name in props) {
+          return props[name]
+        }
+      },
+    })
+
+    /* Some logging */
+    context.log.info('Running...')
+    const now = Date.now()
+
+    /* Run asynchronously in an asynchronous context */
+    const promise = runAsync(context, taskName, async () => {
+      return await this._def.call(build) || undefined
+    }).then((result) => {
+      context.log.notice(`Success ${$ms(Date.now() - now)}`)
+      return result
+    }).catch((error) => {
+      throw context.log.fail(`Failure ${$ms(Date.now() - now)}`, error)
+    }).finally(() => ContextPromises.wait(context))
+
+    /* Cache the resulting promise and return it */
+    cache.set(this, promise)
+    return promise
+  }
+}
+
+/* ========================================================================== *
+ * BUILD COMPILER                                                             *
+ * ========================================================================== */
+
+/** Symbol indicating that an object is a {@link Build} */
+const buildMarker = Symbol.for('plugjs:isBuild')
+
+/** Compile a {@link BuildDef | build definition} into a {@link Build} */
+export function build<
+  D extends BuildDef, B extends ThisBuild<D>
+>(def: D & ThisType<B>): Build<D> {
+  const buildFile = findCaller(build)
+  const tasks: Record<string, Task> = {}
+  const props: Record<string, string> = {}
+
+  /* Iterate through all definition extracting properties and tasks */
+  for (const [ key, val ] of Object.entries(def)) {
+    let len = 0
+    if (typeof val === 'string') {
+      props[key] = val
+    } else if (typeof val === 'function') {
+      tasks[key] = new TaskImpl(buildFile, tasks, props, val)
+      len = key.length
+    } else if (val instanceof TaskImpl) {
+      tasks[key] = val
+      len = key.length
+    }
+
+    /* Update the logger's own "taskLength" for nice printing */
+    /* coverage ignore if */
+    if (len > logOptions.taskLength) logOptions.taskLength = len
+  }
+
+  /* Create the "call" function for this build */
+  const invoke: InvokeBuild = async function invoke(
+      taskNames: string[],
+      overrideProps: Record<string, string | undefined> = {},
+  ): Promise<void> {
+    /* Our "root" logger and initial (empty) state */
+    const logger = getLogger()
+    const state = {
+      cache: new Map<Task, Promise<Result>>(),
+      stack: [] as Task[],
+      props: Object.assign({}, props, overrideProps),
+      tasks: tasks,
+    }
+
+    /* Let's go down to business */
+    logger.notice('Starting...')
+    const now = Date.now()
+
+    try {
+      /* Run tasks _serially_ */
+      for (const name of taskNames) {
+        const task = tasks[name]
+        assert(task, `Task ${$t(name)} not found in build yoooo`)
+        await task.invoke(state, name)
+      }
+      logger.notice(`Build successful ${$ms(Date.now() - now)}`)
+    } catch (error) {
+      throw logger.fail(`Build failed ${$ms(Date.now() - now)}`, error)
+    }
+  }
+
+  /* Create our build, the collection of all props and tasks */
+  const compiled = Object.assign({}, props, tasks) as Build<D>
+
+  /* Sneak our "call" function in the build, for the CLI and "call" below */
+  Object.defineProperty(compiled, buildMarker, { value: invoke })
+
+  /* All done! */
+  return compiled
+}
+
+/** Internal type describing the build invocation function */
+type InvokeBuild = (tasks: string[], props?: Record<string, string | undefined>) => Promise<void>
+
+/** Serially invoke tasks in a {@link Build} optionally overriding properties */
+export async function invoke(
+    build: Build,
+    ...args:
+    | [ ...taskNames: [ string, ...string[] ] ]
+    | [ ...taskNames: [ string, ...string[] ], options: Record<string, string | undefined> ]
+): Promise<void> {
+  const { params: tasks, options: props } = parseOptions(args, {})
+
+  /* Get the calling function from the sneaked-in property in build */
+  const invoke: InvokeBuild = (build as any)[buildMarker]
+
+  /* Triple check that we actually _have_ a function (no asserts here, log!) */
+  if (typeof invoke !== 'function') log.fail('Unknown build type')
+
+  /* Call everyhin that needs to be called */
+  return await invoke(tasks, props)
+}

package/src/files.ts

@@ -1,3 +1,4 @@
+import { assert } from './asserts'
 import { mkdir, writeFile } from './fs'
 import { assertRelativeChildPath, getAbsoluteParent, resolveAbsolutePath } from './paths'
 
@@ -88,9 +89,8 @@ export class Files {
       directory: instance.directory,
 
       add(...files: string[]): FilesBuilder {
-        if (built) throw new Error('FileBuilder "build()" already called')
+        assert(! built, 'FileBuilder "build()" already called')
 
-        if (typeof files === 'string') files = [ files ]
         for (const file of files) {
           const relative = assertRelativeChildPath(instance.directory, file)
           set.add(relative)
@@ -100,7 +100,7 @@ export class Files {
       },
 
       merge(...args: Files[]): FilesBuilder {
-        if (built) throw new Error('FileBuilder "build()" already called')
+        assert(! built, 'FileBuilder "build()" already called')
 
         for (const files of args) {
           for (const file of files.absolutePaths()) {
@@ -124,7 +124,7 @@ export class Files {
       },
 
       build(): Files {
-        if (built) throw new Error('FileBuilder "build()" already called')
+        assert(! built, 'FileBuilder "build()" already called')
 
         built = true
         instance._files.push(...set)

package/src/fs.ts

@@ -30,11 +30,12 @@ const fs = Object.entries(fsp as any).reduce((fs, [ key, val ]) => {
     /* If the value is a function, wrap it! */
     const f = function(...args: any[]): any {
       /* Call the function, and _catch_ any error */
-      return val.apply(fsp, args).catch((error: any) => {
-        /* For any error caught, we fill in the stack trace */
-        Error.captureStackTrace(error)
-        throw error
-      })
+      return val.apply(fsp, args)
+          .catch(/* coverage ignore next*/ (error: any) => {
+            /* For any error caught, we fill in the stack trace */
+            Error.captureStackTrace(error)
+            throw error
+          })
     }
 
     /* Make sure that the functions are called correctly */

package/src/helpers.ts

@@ -1,3 +1,7 @@
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { mkdtempSync } from 'node:fs'
+
 import { assert, assertPromises } from './asserts'
 import { requireContext } from './async'
 import { Files } from './files'
@@ -65,6 +69,7 @@ export async function rmrf(directory: string): Promise<void> {
   assert(dir !== context.resolve('@'),
       `Cowardly refusing to wipe build file directory ${$p(dir)}`)
 
+  /* coverage ignore if */
   if (! resolveDirectory(dir)) {
     log.info('Directory', $p(dir), 'not found')
     return
@@ -159,6 +164,17 @@ export function isDirectory(...paths: [ string, ...string[] ]): AbsolutePath | u
   return resolveDirectory(path)
 }
 
+/**
+ * Create a temporary directory and return its {@link AbsolutePath}.
+ *
+ * The directory will be rooted in `/tmp` or wherever `os.tmpdir()` decides.
+ */
+export function mkdtemp(): AbsolutePath {
+  const prefix = join(tmpdir(), 'plugjs-')
+  const path = mkdtempSync(prefix)
+  return resolve(path)
+}
+
 /**
  * Execute a command and await for its result from within a task.
  *

package/src/paths.ts

@@ -14,9 +14,8 @@ export type AbsolutePath = string & { __brand_absolute_path: never }
 
 /** Resolve a path into an {@link AbsolutePath} */
 export function resolveAbsolutePath(directory: AbsolutePath, ...paths: string[]): AbsolutePath {
-  const resolved = resolve(directory, ...paths) as AbsolutePath
-  assert(isAbsolute(resolved), `Path "${join(...paths)}" resolved in "${directory}" is not absolute`)
-  return resolved
+  assertAbsolutePath(directory)
+  return resolve(directory, ...paths) as AbsolutePath
 }
 
 /**
@@ -32,8 +31,6 @@ export function resolveAbsolutePath(directory: AbsolutePath, ...paths: string[])
  * ```
  */
 export function resolveRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string | undefined {
-  assertAbsolutePath(directory)
-
   const abs = resolveAbsolutePath(directory, ...paths)
   const rel = relative(directory, abs)
   return (isAbsolute(rel) || (rel === '..') || rel.startsWith(`..${sep}`)) ? undefined : rel
@@ -43,7 +40,6 @@ export function resolveRelativeChildPath(directory: AbsolutePath, ...paths: stri
  * Asserts that a path is a relative path to the directory specified, failing
  * the build if it's not (see also {@link resolveRelativeChildPath}).
  */
-
 export function assertRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string {
   const relative = resolveRelativeChildPath(directory, ...paths)
   assert(relative, `Path "${join(...paths)}" not relative to "${directory}"`)
@@ -76,6 +72,38 @@ export function getCurrentWorkingDirectory(): AbsolutePath {
   return cwd
 }
 
+/**
+ * Return the _common_ path amongst all specified paths.
+ *
+ * While the first `path` _must_ be an {@link AbsolutePath}, all other `paths`
+ * can be _relative_ and will be resolved against the first `path`.
+ */
+export function commonPath(path: AbsolutePath, ...paths: string[]): AbsolutePath {
+  assertAbsolutePath(path)
+
+  // Here the first path will be split into its components
+  // on win => [ 'C:', 'Windows', 'System32' ]
+  // on unx => [ '', 'usr'
+  const components = normalize(path).split(sep)
+
+  let length = components.length
+  for (const current of paths) {
+    const absolute = resolveAbsolutePath(path, current)
+    const parts = absolute.split(sep)
+    for (let i = 0; i < length; i++) {
+      if (components[i] !== parts[i]) {
+        length = i
+        break
+      }
+    }
+
+    assert(length, 'No common ancestors amongst paths')
+  }
+
+  const common = components.slice(0, length).join(sep)
+  assertAbsolutePath(common)
+  return common
+}
 
 /* ========================================================================== *
  * MODULE RESOLUTION FUNCTIONS                                                *
@@ -130,7 +158,7 @@ export function requireResolve(__fileurl: string, module: string): AbsolutePath
     // ... then delegate to the standard "require.resolve(...)"
     const url = pathToFileURL(file)
     const ext = extname(file)
-    const checks = ext ? [ `${module}`, `${module}${ext}`, `${module}/index${ext}` ] : [ module ]
+    const checks = [ `${module}`, `${module}${ext}`, `${module}/index${ext}` ]
 
     for (const check of checks) {
       const resolved = fileURLToPath(new URL(check, url)) as AbsolutePath
@@ -147,39 +175,6 @@ export function requireResolve(__fileurl: string, module: string): AbsolutePath
   return required
 }
 
-/**
- * Return the _common_ path amongst all specified paths.
- *
- * While the first `path` _must_ be an {@link AbsolutePath}, all other `paths`
- * can be _relative_ and will be resolved against the first `path`.
- */
-export function commonPath(path: AbsolutePath, ...paths: string[]): AbsolutePath {
-  assertAbsolutePath(path)
-
-  // Here the first path will be split into its components
-  // on win => [ 'C:', 'Windows', 'System32' ]
-  // on unx => [ '', 'usr'
-  const components = normalize(path).split(sep)
-
-  let length = components.length
-  for (const current of paths) {
-    const absolute = resolveAbsolutePath(path, current)
-    const parts = absolute.split(sep)
-    for (let i = 0; i < length; i++) {
-      if (components[i] !== parts[i]) {
-        length = i
-        break
-      }
-    }
-
-    assert(length, 'No common ancestors amongst paths')
-  }
-
-  const common = components.slice(0, length).join(sep)
-  assertAbsolutePath(common)
-  return common
-}
-
 /* ========================================================================== *
  * FILE CHECKING FUNCTIONS                                                    *
  * ========================================================================== */