@architect/inventory 2.2.1-RC.0 → 3.0.0-RC.10

package/src/config/project/{prefs.js → prefs/index.js}

@@ -1,30 +1,37 @@
-let read = require('../../read')
-let validate = require('./validate')
-let is = require('../../lib/is')
+let { join } = require('path')
+let { existsSync, readFileSync } = require('fs')
+let read = require('../../../read')
+let validate = require('../validate')
+let { is, validationPatterns: valid } = require('../../../lib')
+let { parse } = require('./dotenv')
 let { homedir } = require('os')
 
 module.exports = function getPrefs ({ scope, inventory, errors }) {
   let cwd = scope === 'global'
     ? homedir()
-    : inventory._project.src
+    : inventory._project.cwd
 
-  // Populate preferences
+  let envFilepath = join(cwd, '.env')
+  let hasEnvFile = scope === 'local' && existsSync(envFilepath)
   let prefs = read({ type: 'preferences', cwd, errors })
-  if (prefs.filepath) {
-    let preferences = {}
+
+  if (!prefs.filepath && !hasEnvFile) return null
+
+  let preferences = {}
+
+  // Populate Architect preferences
+  if (prefs.filepath && prefs.arc) {
     // Ok, this gets a bit hairy
     // Arc outputs an object of nested arrays
     // Basically, construct a pared-down intermediate prefs obj for consumers
     Object.entries(prefs.arc).forEach(([ key, val ]) => {
-      // TODO add additional preferences checks and normalization
-
-      /* istanbul ignore else */ // Parser should get this, but jic
+      /* istanbul ignore else: Parser should get this, but jic */
       if (!preferences[key]) preferences[key] = {}
-      /* istanbul ignore else */ // Parser should only produce arrays, but jic
+      /* istanbul ignore else: Parser should only produce arrays, but jic */
       if (is.array(val)) {
         val.forEach(v => {
           if (is.array(v)) {
-            /* istanbul ignore if */ // Single vals should be strings, but jic
+            /* istanbul ignore if: Single vals should be strings, but jic */
             if (v.length === 1) preferences[key] = v[0]
             if (v.length === 2) preferences[key][v[0]] = v[1]
             if (v.length > 2)   preferences[key][v[0]] = [ ...v.slice(1) ]
@@ -39,35 +46,47 @@ module.exports = function getPrefs ({ scope, inventory, errors }) {
       // Turn env vars with spaces into strings
       if (key === 'env') {
         [ 'testing', 'staging', 'production' ].forEach(e => {
-          /* istanbul ignore else */ // Yet another jic
+          /* istanbul ignore else: Yet another jic */
           if (preferences.env[e]) {
             Object.entries(preferences.env[e]).forEach(([ key, val ]) => {
+              if (!valid.envVar.test(key)) {
+                errors.push(`Env var '${key}' is invalid, must be [a-zA-Z0-9_]`)
+              }
               if (is.array(val)) preferences.env[e][key] = val.join(' ')
             })
           }
+          else preferences.env[e] = null
         })
       }
       // Turn Sandbox scripts into commands
       if (key === 'sandbox-startup') {
         preferences[key] = val.map(v => {
           if (is.string(v)) return v
-          /* istanbul ignore else */ // Yet another jic
+          /* istanbul ignore else: Yet another jic */
           if (is.array(v)) return v.join(' ')
         })
       }
     })
 
     validate(preferences, errors)
+  }
 
-    return {
-      preferences: {
-        ...preferences,
-        _arc: prefs.arc,
-        _raw: prefs.raw,
-      },
-      preferencesFile: prefs.filepath
+  // Populate .env (testing environment only, disables other env vars)
+  if (hasEnvFile) {
+    let dotenv = parse(readFileSync(envFilepath))
+    preferences.env = {
+      testing: Object.keys(dotenv).length ? dotenv : null,
+      staging: null,
+      production: null,
     }
   }
 
-  return null
+  return {
+    preferences: {
+      ...preferences,
+      _arc: prefs.arc,
+      _raw: prefs.raw,
+    },
+    preferencesFile: prefs.filepath
+  }
 }

package/src/config/project/validate/index.js

@@ -1,13 +1,20 @@
-let is = require('./../../../lib/is')
+let { is } = require('./../../../lib')
 
 module.exports = function validatePreferences (preferences, errors) {
   // Env checks
-  let { env } = preferences
-  if (!env) return
-  if (env && !is.object(env)) errors.push(`Invalid preferences setting: @env ${env}`)
-
+  let { env, sandbox } = preferences
   let envs = [ 'testing', 'staging', 'production' ]
-  envs.forEach(e => {
-    if (env[e] && !is.object(env[e])) errors.push(`Invalid preferences setting: @env ${e}`)
-  })
+
+  if (env && !is.object(env)) {
+    errors.push(`Invalid preferences setting: @env ${env}`)
+  }
+  else if (env) {
+    envs.forEach(e => {
+      if (env[e] && !is.object(env[e])) errors.push(`Invalid preferences setting: @env ${e}`)
+    })
+  }
+
+  if (sandbox?.env && !envs.includes(sandbox.env)) {
+    errors.push(`Invalid preferences setting: @sandbox env ${sandbox.env}`)
+  }
 }

package/src/defaults/index.js

@@ -1,38 +1,45 @@
+let { join } = require('path')
 let fnConfig = require('./function-config')
-let pragmas = require('../lib/pragmas')
+let { pragmas } = require('../lib')
 
 /**
  * Returns a default stub inventory object
  * - Every possible officially supported value should be present
  */
 module.exports = function inventoryDefaults (params = {}) {
-  let { cwd, region } = params
+  let { cwd = process.cwd(), deployStage = null, region } = params
   // Allow region env var override
-  region = process.env.AWS_REGION || region || 'us-west-2'
+  region = region || process.env.AWS_REGION || 'us-west-2'
   let defaultFunctionConfig = fnConfig()
   return {
     // Meta
     _arc: {
       version: 'Unknown',     // @architect/architect semver (if installed)
       defaultFunctionConfig,  // Architect's default function config
-      pragmas,                // Registry of all + Lambda pragmas
+      pragmas,                // Registry of all, Lambda, reserved, retired pragmas
+      deployStage,            // Deploy stage of the running project (if specified)
     },
     _project: {
       type: 'aws',
-      src: cwd,
+      cwd,                          // Project root dir
+      src: join(cwd, 'src'),        // Default source tree dir
+      build: null,                  // Optional build artifact dir
       manifest: null,               // Root project manifest filename
-      // manifestCreated            // TODO
-      preferences: null,            // Realized preferences obj, resolved from global > local
+      preferences: null,            // Realized preferences obj, resolved from local > global
       localPreferences: null,       // Local preferences obj
       localPreferencesFile: null,   // Local preferences file path
       globalPreferences: null,      // Global preferences obj
       globalPreferencesFile: null,  // Global preferences file path
       defaultFunctionConfig,        // Project-level function config
       rootHandler: null,            // null | configured | arcStaticAssetProxy | proxy
-      plugins: null,                // `require`d plugin modules as a map of plugin name to module
+      env: {                        // Env vars pulled from:
+        local: null,                // - Local/global prefs or .env
+        plugins: null,              // - Plugins
+        aws: null,                  // - SSM
+      },
+      customRuntimes: null,         // Runtime plugins
       arc: [],                      // Raw arc obj
       raw: '',                      // Raw arc string
-      env: null,                    // Env vars pulled from SSM (if enabled)
     },
     // App + vendor config
     app: '',
@@ -52,9 +59,7 @@ module.exports = function inventoryDefaults (params = {}) {
     cdn: null,
     events: null,
     http: null,
-    indexes: null,
-    macros: null,
-    plugins: null, // These are the Lambdas created by plugins, not the plugin modules, which are in _project.plugins
+    plugins: null,
     proxy: null,
     queues: null,
     scheduled: null,
@@ -65,7 +70,9 @@ module.exports = function inventoryDefaults (params = {}) {
     'tables-streams': null,
     views: null,
     ws: null,
-    // Collection of all Lambda paths
+    // Unclassified / non-pragma custom Lambdas created by plugins
+    customLambdas: null,
+    // Collection of all Lambda source paths
     lambdaSrcDirs: null,
     // Lambda lookup by source directory
     lambdasBySrcDir: null,

package/src/env/index.js

@@ -1,76 +1,91 @@
+let { mergeEnvVars } = require('../lib')
+
 /**
  * Read env vars out of SSM
  */
 module.exports = function env (params, inventory, callback) {
-  if (params.env) {
-    /* istanbul ignore next */
-    try {
-      // eslint-disable-next-line
-      var aws = require('aws-sdk')
-    }
-    catch (err) {
-      let msg = `'aws-sdk' not found, please install locally or globally (see also readme#aws-sdk-caveat)`
-      return callback(Error(msg))
-    }
-    let name = inventory.app
-    let { region } = inventory.aws
-    let ssm = new aws.SSM({ region })
-    let result = []
-
-    function getSomeEnvVars (name, NextToken, callback) {
-      // Base query to ssm
-      let query = {
-        Path: `/${name}`,
-        Recursive: true,
-        MaxResults: 10,
-        WithDecryption: true
-      }
+  if (!params.env) {
+    return callback()
+  }
 
-      // Check if we're paginating
-      /* istanbul ignore if */
-      if (NextToken) query.NextToken = NextToken
+  /* istanbul ignore next */
+  try {
+    // eslint-disable-next-line
+      var aws = require('aws-sdk')
+  }
+  catch (err) {
+    let msg = `'aws-sdk' not found, please install locally or globally (see also readme#aws-sdk-caveat)`
+    return callback(Error(msg))
+  }
+  let name = inventory.app
+  let { region } = inventory.aws
+  let ssm = new aws.SSM({ region })
+  let result = []
 
-      // Perform the query
-      ssm.getParametersByPath(query, function _query (err, data) {
-        if (err) callback(err)
-        else {
-          // Tidy up the response
-          result = result.concat(data.Parameters.map(function (param) {
-            let bits = param.Name.split('/')
-            return {
-              app: name, // jic
-              env: bits[2],
-              name: bits[3],
-              value: param.Value,
-            }
-          }))
-          // Check for more data and, if so, recurse
-          /* istanbul ignore if */ // Sadly no way to easily mock this for testing
-          if (data.NextToken) {
-            getSomeEnvVars(name, data.NextToken, callback)
-          }
-          else callback(null, result)
-        }
-      })
+  function getSomeEnvVars (name, NextToken, callback) {
+    // Base query to ssm
+    let query = {
+      Path: `/${name}`,
+      Recursive: true,
+      MaxResults: 10,
+      WithDecryption: true
     }
 
-    getSomeEnvVars(name, false, function done (err, result) {
+    // Check if we're paginating
+    /* istanbul ignore if */
+    if (NextToken) query.NextToken = NextToken
+
+    // Perform the query
+    ssm.getParametersByPath(query, function _query (err, data) {
       if (err) callback(err)
       else {
-        if (result.length) {
-          let testing = null
-          let staging = null
-          let production = null
-          result.forEach(r => {
-            if (r.env === 'testing') testing = Object.assign({}, testing, { [r.name]: r.value })
-            if (r.env === 'staging') staging = Object.assign({}, staging, { [r.name]: r.value })
-            if (r.env === 'production') production = Object.assign({}, production, { [r.name]: r.value })
-          })
-          inventory._project.env = { testing, staging, production }
+        // Tidy up the response
+        result = result.concat(data.Parameters.map(function (param) {
+          let bits = param.Name.split('/')
+          return {
+            app: name, // jic
+            env: bits[2],
+            name: bits[3],
+            value: param.Value,
+          }
+        }))
+        // Check for more data and, if so, recurse
+        /* istanbul ignore if: Sadly no way to easily mock this for testing */
+        if (data.NextToken) {
+          getSomeEnvVars(name, data.NextToken, callback)
         }
-        callback()
+        else callback(null, result)
       }
     })
   }
-  else callback()
+
+  getSomeEnvVars(name, false, function done (err, result) {
+    if (err) callback(err)
+    else {
+      let testing = null
+      let staging = null
+      let production = null
+      if (result.length) {
+        // TODO refactor into a reducer?
+        result.forEach(({ env, name: k, value: v }) => {
+          if (env === 'testing') testing = Object.assign({}, testing, { [k]: v })
+          if (env === 'staging') staging = Object.assign({}, staging, { [k]: v })
+          if (env === 'production') production = Object.assign({}, production, { [k]: v })
+        })
+      }
+
+      let errors = []
+      inventory._project.env.aws = mergeEnvVars({
+        env: 'Application',
+        source: inventory._project.env.plugins,
+        target: { testing, staging, production },
+        errors,
+      })
+      if (errors.length) {
+        callback(Error(errors[0]))
+        return
+      }
+      callback()
+    }
+  })
 }

package/src/get.js

@@ -1,4 +1,4 @@
-let is = require('./lib/is')
+let { is } = require('./lib')
 
 module.exports = function _get (inventory) {
   function getter (prag, name) {
@@ -38,5 +38,4 @@ module.exports = function _get (inventory) {
 // These refer to other pragmas, and thus may allow multiple same/same-named entities
 let multipleResults = [
   'tables-indexes',
-  'indexes',
 ]

package/src/index.js

@@ -5,7 +5,7 @@ let config = require('./config')
 let getEnv = require('./env')
 let validate = require('./validate')
 let get = require('./get')
-let errorFmt = require('./lib/error-fmt')
+let { errorFmt } = require('./lib')
 
 /**
  * Architect Inventory
@@ -50,10 +50,7 @@ module.exports = function architectInventory (params = {}, callback) {
 
   // Exit early if supplied Arc is fundamentally broken
   if (errors.length) {
-    callback(errorFmt({
-      type: 'manifest',
-      errors,
-    }))
+    callback(errorFmt({ type: 'manifest', errors }))
     return promise
   }
 
@@ -61,27 +58,32 @@ module.exports = function architectInventory (params = {}, callback) {
   let inventory = inventoryDefaults(params)
 
   // Set up project params for config
-  let project = { cwd, arc, raw, filepath, inventory }
+  let project = { arc, cwd, errors, filepath, inventory, raw }
 
   // Populate inventory.arc
   inventory._arc = config._arc(project)
 
+  // @plugins come first, as they register hooks all around the project
+  inventory.plugins = config.pragmas.plugins(project)
+
   // Establish default function config from project + Arc defaults
-  inventory._project = config._project(project, errors)
+  inventory._project = config._project(project)
+
+  // End here if plugins failed
+  if (errors.length) {
+    callback(errorFmt({ type: 'plugin', errors }))
+    return promise
+  }
 
-  // Userland: fill out the pragmas
+  // Userland: fill out the pragmas, starting with @plugins
   inventory = {
     ...inventory,
-    ...config.pragmas(project, errors)
+    ...config.pragmas(project)
   }
 
-  // End here if first-pass pragma validation failed
+  // End here if first-pass validation failed
   if (errors.length) {
-    callback(errorFmt({
-      type: 'validation',
-      errors,
-      inventory,
-    }))
+    callback(errorFmt({ type: 'validation', errors }))
     return promise
   }
 

package/src/lib/asap-src.js

@@ -17,7 +17,7 @@ module.exports = function asapSrc () {
   try {
     return require.resolve('@architect/asap')
   }
-  catch (err) { /* Swallow */ }
-
-  throw Error('Cannot find ASAP module!')
+  catch (err) {
+    throw Error('Cannot find ASAP module!')
+  }
 }

package/src/lib/error-fmt.js

@@ -1,26 +1,18 @@
-let { basename } = require('path')
-
 /**
  * Common error formatter
  *
  * @param params {object}
  * @param params.type {string} - Inventory error type: `manifest`, `validation`, or `configuration`
  * @param params.errors {array} - Array of one or more errors to output
- * @param params.meta {string} - Appends optional info to primary error message
  * @param params.inventory {object} - Inventory object
  *
  * @returns Formatted Error + appended ARC_ERRORS property
  */
 module.exports = function format (params) {
-  let { type, errors, meta, inventory } = params
-  if (!meta && type === 'validation') {
-    meta = inventory._project.manifest
-      ? ` in ${basename(inventory._project.manifest)}`
-      : ''
-  }
+  let { type, errors } = params
   let output = errors.map(err => `- ${err}`).join('\n')
   let errType = type[0].toUpperCase() + type.substr(1)
-  let err = Error(`${errType} error${errors.length > 1 ? 's' : ''}${meta ? meta : ''}:\n${output}`)
+  let err = Error(`${errType} error${errors.length > 1 ? 's' : ''}:\n${output}`)
   err.ARC_ERRORS = { type, errors }
   return err
 }

package/src/lib/get-lambda-dirs.js

@@ -0,0 +1,37 @@
+let { isAbsolute, join } = require('path')
+
+/**
+ * Get the src (and build) dirs for a Lambda
+ * - Arc Lambdas: pass a name + pragma || relative file path
+ * - Plugin Lambdas: pass a relative file path || absolute file path
+ */
+function getLambdaDirs (params, options) {
+  let { cwd, item, projSrc, projBuild, type: pragma } = params
+  let { name, plugin, customSrc } = options
+  let lambdaDirs = {}
+
+  if (plugin) {
+    let src = normalizeSrc(cwd, item.src)
+    lambdaDirs.src = src
+    if (projBuild) {
+      lambdaDirs.build = src.replace(src, projBuild)
+    }
+  }
+  else {
+    let root = customSrc ? cwd : projSrc
+    let path = customSrc || join(pragma, name)
+    lambdaDirs.src = join(root, path)
+    if (projBuild) {
+      lambdaDirs.build = join(projBuild, path)
+    }
+  }
+  return lambdaDirs
+}
+
+function normalizeSrc (cwd, dir) {
+  if (isAbsolute(dir)) return dir
+  return join(cwd, dir)
+}
+
+getLambdaDirs.normalizeSrc = normalizeSrc
+module.exports = getLambdaDirs

package/src/lib/index.js

@@ -0,0 +1,42 @@
+let asapSrc = require('./asap-src')
+let errorFmt = require('./error-fmt')
+let getLambdaDirs = require('./get-lambda-dirs')
+let is = require('./is')
+let mergeEnvVars = require('./merge-env-vars')
+let pragmas = require('./pragmas')
+
+/**
+ * Why take up a whole fs block when smol libs can just live here?
+ */
+
+// For setting `lambda.build`, compiled + transpiled are effectively the same
+let compiledRuntimes = [ 'compiled', 'transpiled' ]
+
+// `any` must come last for Sandbox route sorting purposes
+let httpMethods = [ 'get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'any' ]
+
+let validationPatterns = {
+  strictName: /^[a-z][a-z0-9-]+$/,
+  looseName: /^[a-z][a-zA-Z0-9-_]+$/,
+  looserName: /^[a-z][a-zA-Z0-9-._]+$/,
+  veryLooseName: /^[a-zA-Z0-9/\-._]*$/,
+  // IEEE 1003.1-2001 does not allow lowercase, so consider this a compromise for the Windows folks in the house
+  envVar: /^[a-zA-Z0-9_]+$/,
+}
+
+// Error tidier: remove the error name, just print the message + stack data
+let tidyError = err => err.message + `\n` + err.stack.split('\n').slice(1).join('\n')
+
+module.exports = {
+  asapSrc,
+  compiledRuntimes,
+  errorFmt,
+  getLambdaDirs,
+  httpMethods,
+  is,
+  mergeEnvVars,
+  normalizeSrc: getLambdaDirs.normalizeSrc,
+  pragmas,
+  tidyError,
+  validationPatterns,
+}

package/src/lib/is.js

@@ -4,10 +4,12 @@ module.exports = {
   // Types
   array: item => Array.isArray(item),
   bool: item => typeof item === 'boolean',
+  defined: item => typeof item !== 'undefined',
+  fn: item => typeof item === 'function',
+  nullish: item => typeof item === 'undefined' || item === null,
   number: item => Number.isInteger(item),
   object: item => typeof item === 'object' && !Array.isArray(item),
   string: item => typeof item === 'string',
-  defined: item => typeof item !== 'undefined' && item !== null,
   // Filesystem
   exists: path => existsSync(path),
   folder: path => existsSync(path) && lstatSync(path).isDirectory(),

package/src/lib/merge-env-vars.js

@@ -0,0 +1,32 @@
+let envs = [ 'testing', 'staging', 'production' ]
+
+module.exports = function mergeEnvVars (params) {
+  let { name, source, target, errors } = params
+  if (source === null) return target
+  if (target === null) return source
+  let probs = []
+
+  // Deep copy to reset any potential refs
+  let merged = JSON.parse(JSON.stringify(target))
+  envs.forEach(env => {
+    if (!source[env]) return
+    Object.keys(source[env]).forEach(k => {
+      if (merged[env]?.[k]) {
+        probs.push(`'${env}' variable '${k}'`)
+      }
+      else {
+        if (!merged[env]) merged[env] = {}
+        merged[env][k] = source[env][k]
+      }
+    })
+  })
+
+  if (probs.length) {
+    let s = probs.length > 1 ? 's' : ''
+    let msg = `${name} env var${s} conflicts with plugin:\n` +
+              `- ${probs.join('\n- ')}`
+    errors.push(msg)
+  }
+
+  return merged
+}

package/src/lib/pragmas.js

@@ -6,8 +6,6 @@ module.exports = {
     'cdn',
     'events',
     'http',
-    'indexes', // -> transitioning to @tables-indexes
-    'macros',
     'plugins',
     'proxy',
     'queues',
@@ -24,10 +22,28 @@ module.exports = {
   lambdas: [
     'events',
     'http',
-    'plugins',
     'queues',
     'scheduled',
     'tables-streams',
     'ws',
   ],
+  // Reserved pragma names that map to internal Inventory properties
+  reserved: [
+    'customLambdas',
+  ],
+  // Retired pragmas no longer in active use
+  retired: [
+    'indexes',
+    'macros',
+    'slack',
+    'streams', // Never fully launched
+    // Static types
+    'css',
+    'html',
+    'js',
+    'json',
+    'jsonapi',
+    'text',
+    'xml',
+  ]
 }