@leverege/build-tools 1.8.4

package/src/overwhelm

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+const chalk = require( 'chalk' )
+const cliArgs = require( 'command-line-args' )
+const cliHelp = require( 'command-line-usage' )
+const exec = require( 'child_process' ).execSync
+const fs = require( 'fs' )
+const glob = require( 'glob' )
+const parse = require( 'parse-gitignore' )
+const ask = require( 'readline-sync' )
+const YAML = require( 'js-yaml' )
+
+const optionsDefinitions = [
+  { name : 'section',  alias : 's', type : String, default : 'default' },
+  { name : 'key',      alias : 'k', type : String },
+  { name : 'export',   alias : 'e', type : Boolean, default : false },
+  { name : 'continue', alias : 'c', type : Boolean, default : false },
+  { name : 'verbose',  alias : 'v', type : Boolean, default : false },
+]
+const args = cliArgs( optionsDefinitions )
+
+// The kubernetes context is equal to the git branch name.
+const context = require( 'git-branch' ).sync()
+
+if ( context == 'master' ) {
+  console.log( '***ERROR: master context is forbidden; change to a different branch\n\n' )
+  process.exit( 1 )
+}
+
+// Load the default values and then overlay with the project specific yaml
+// values. This supports the notion of this type of approach in the
+// overwhelm yaml settings:
+//   default:
+//     GCE_MACHINE : "n1-standard-2"
+//
+//   my-project:
+//     GCE_MACHINE : "n1-highcpu-8"
+//
+// where the my-project specific setting may override the default if it
+// needs a beefier deployment. Any setting can be defaulted in this
+// fashion, but it is advised not to set a default region with this
+// approach in order to keep us cognizant of exactly where a cluster is
+// being formed.
+//
+const yaml = YAML.safeLoad( fs.readFileSync( 'overwhelm.yaml', 'utf-8' ) )
+const over = yaml.default
+const cfgs = yaml[context]
+
+if ( !cfgs ) {
+  console.log( `***ERROR: Unknown context => [${context}]\n` )
+  console.log( '   Known k8s contexts are:' )
+  Object.keys( yaml ).forEach( ( key ) => {
+    if ( key !== 'default' ) { console.log( `             ${key}` ) }
+  } )
+  console.log( `Add a section into overwhelm.yaml for ${context}\n\n` )
+  process.exit( 1 )
+}
+
+Object.keys( cfgs ).forEach( ( key ) => { over[key] = cfgs[key] || over[key] } )
+
+// Expand any variables that reference other variable settings. A perfect
+// example of where this is useful is in the setting of a PROJECT_NAME and
+// a PROJECT_ID. Most of the time these values are identical, which is why
+// this setting exists in the default section:
+//   default:
+//     PROJECT_ID : ${PROJECT_NAME}
+//
+// However, in the case of projects like Siren Marine, this is the more
+// likely setup due to legacy naming schemes:
+//   sire-marine:
+//     PROJECT_NAME : siren-marine
+//     PROJECT_ID   : prod-rt-data
+//
+const varErrors = []
+Object.keys( over ).forEach( ( key ) => {
+  if ( !over[key] ) return // no value to work with - skip it
+
+  // Look for something in the form of "thing-${VAR1}-${VAR2}-${VARn}-stuff"
+  const matches = over[key].match( /\$\{\w+\}/g )
+  if ( !matches ) return
+
+  matches.forEach( ( replaceThis ) => {
+    // The matched variable names will be in the form of ${VARNAME} so drop
+    // the ${} characters before using the VARNAME to map into the
+    // overwhelm map containing the desired replacement value.
+    const withThat = over[replaceThis.replace( /\W+/g, '' )]
+    if ( !withThat ) {
+      varErrors.push( `${key} : ${over[key]}` )
+      return
+    }
+    // Store the replaced string back in the overwhelm value map.
+    over[key] = over[key].replace( replaceThis, withThat )
+  } )
+} )
+
+if ( varErrors.length > 0 ) {
+  console.log( '***ERROR: unkown variable reference(s) in overwhelm.yaml:\n' )
+  varErrors.forEach( ( error ) => {
+    console.log( `     ${error}` )
+  } )
+  console.log('' )
+  process.exit( 1 )
+}
+
+// Grab a list of the existing yaml templates.
+const yams = glob.sync( 'values-*.yaml' )
+
+// A function to apply the replacements to all of the matching yaml which
+// will error out if it runs into an unknown OVH<tag>.
+const doReplacements = ( yamls, replacements ) => {
+  let replYaml = yamls
+
+  Object.keys( replacements ).forEach( ( repl ) => {
+    const replaceThis = new RegExp( `OVH:<${repl}>`, 'g' )
+    const withThat = `${replacements[repl]}`
+    replYaml = replYaml.replace( replaceThis, withThat )
+  } )
+
+  // Verify all replaceables have been handled, or error out.
+  const missed = replYaml.match( /OVH:<(.*)>/g )
+
+  if ( missed ) {
+    console.log( '\n***ERROR: missing replacements in overwhelm.yaml for these tags:\n' )
+    missed.forEach( ( miss ) => {
+      console.log( `     TAG: ${miss.match( /OVH:<(.*)>/)[1]}` )
+    } )
+    console.log('' )
+    process.exit( 1 )
+  }
+
+  return replYaml
+}
+
+// Collect all of the yaml from the yams, and always expect the default and
+// platform yamls to be in that list.
+const buildYaml = ( yamls, replacements ) => {
+  // We always start with default but values-platform is no longer needed.
+  const always = [ 'values-default.yaml' ]
+  const values = [ ...always, ...yamls ]
+  const loaded = []
+  let allYamls = ''
+
+  values.forEach( ( yaml ) => {
+    if ( !fs.existsSync( yaml ) ) {
+      console.log( `\n***ERROR: yaml file missing => ${yaml}\n` )
+      process.exit( 1 )
+    }
+
+    if ( !loaded.includes( yaml ) ) {
+      allYamls += `\n# AHOY => ${yaml}\n\n`
+      allYamls += fs.readFileSync( yaml, { encoding : 'utf-8' } )
+      loaded.push( yaml )
+    }
+  } )
+
+  // Now apply all of the replacements from the overwhelm file.
+  return doReplacements( allYamls, replacements )
+}
+
+// Call buildYaml to replace the OVH strings in the yaml files.
+const values = buildYaml( yams, over )
+
+// Check to see if someone is requesting a value from the yaml.
+if ( args.key ) {
+  const section = args.section || 'default'
+  const keys = yaml[section]
+  if ( args.verbose ) {
+    console.log( 'replacements' )
+    console.log( keys )
+  }
+  if ( args.export ) {
+    console.log( `export ${args.key}=${keys[args.key]}` )
+  }
+  else {
+    console.log( keys[args.key] )
+  }
+  if ( ! args.continue ) process.exit()
+}
+
+// Find all of the potential target dirs. Utilize .gitignore to ignore files
+const opt = {
+  ignore : parse( fs.readFileSync( '.gitignore' ) )
+}
+
+const ahoy = glob.sync( '*/', opt )
+
+// Keel supports a "never" policy which will cause it to skip over a release
+// if it is properly set. Adding a .nokeel file to a release directoy will
+// cause the creation of the file if it does not already exist.
+const generateKeelNeverPolicy = ( fileName ) => {
+  if ( fs.existsSync( fileName ) ) return
+  const neverPolicy = `
+keel:
+  # keel policy (all/major/minor/patch/force)
+  policy: "never"
+  # approvals
+# approvals: 1
+# approvalDeadline: 24
+# # images to track and update
+# images:
+#   - repository: never.IMAGE # [1]
+#     tag: never.VERSION  # [2]
+`
+  fs.writeFileSync( fileName, neverPolicy )
+}
+
+// Generate the values.yaml files in directories not marked with .nohelm.
+ahoy.forEach( ( dir ) => {
+  if ( !fs.existsSync( `${dir}/.nohelm` ) ) {
+    console.log( `Generating values in ${dir}` )
+
+    let valuesOut = [] // An accumulator for all of the output values.
+
+    // Add support for localized values for things like keel (or whatever)
+    const valuesLocal = `${dir}values-local.yaml`
+
+    if ( fs.existsSync( `${dir}.nokeel` ) ) {
+      generateKeelNeverPolicy( valuesLocal )
+    }
+
+    if ( fs.existsSync( valuesLocal ) ) {
+      console.log( `     Local values in ${valuesLocal}` )
+      valuesOut += `\n# AHOY => values-local.yaml\n\n`
+      valuesOut += fs.readFileSync( valuesLocal, { encoding : 'utf-8' } )
+    }
+    valuesOut += `\n${values}`
+    valuesOut  = doReplacements( valuesOut, over )
+
+    fs.writeFileSync( `${dir}/values.yaml`, valuesOut )
+  }
+} )
+
+// Set the GCP context for safety!
+  const clusterName = over['CLUSTER_NAME']
+  const projectName = over['PROJECT_NAME']
+  const zone = over['GCE_REGION'] + ( over['GCE_ZONE'] ? `-${over['GCE_ZONE']}` : '' )
+
+  if ( !clusterName ) {
+    console.log( chalk.yellow(
+    `
+
+    The overwhelm.yaml file in this branch is missing a CLUSTER_NAME setting,
+    which was added to support cluster names that do not match the project
+    name. Since the mismatch is rare, you can probably get by with simply
+    adding this line following PROJECT_NAME in the default section of
+    overwhelm.yaml:
+
+      ${chalk.bold.green( `CLUSTER_NAME   : "\${PROJECT_NAME}"` )}
+
+    However, if the CLUSTER_NAME is not the same as the PROJECT_NAME then go
+    ahead and add the CLUSTER_NAME setting to the ${chalk.bold.green(projectName)} section of the
+    overwhelm.yaml file.
+
+    ` ) )
+    process.exit( 1 )
+  }
+
+  let kubeout = '_no_current_context_'
+  try {
+    // if current is not set exec will throw
+    kubeout = exec( 'kubectl config current-context' )
+  } catch (err) { }
+
+  const currentCtx = kubeout.toString().trim()
+  const desiredCtx = `gke_${projectName}_${zone}_${clusterName}`
+  const matchedCtx = ( currentCtx === desiredCtx )
+  const cmd = `gcloud container clusters get-credentials ${clusterName} --zone ${zone} --project ${projectName}`
+  
+  if ( matchedCtx ) {
+    console.log( `
+
+  Your current context matches. Do you want to update credentials anyway?
+
+  ` )
+  }
+  else {
+    console.log( `
+
+  You are about to change your GCP context to:
+      CLUSTER_NAME => ${chalk.bold.green(clusterName)}
+      PROJECT_NAME => ${chalk.bold.green(projectName)}
+      GCE_REGION   => ${chalk.bold.green(zone)}
+
+  ` )
+  }
+  const ans = ask.question( `Enter "${chalk.bold.green( 'yes' )}" if you wish to proceed => ` )
+  if ( ans !== 'yes' ) {
+    if ( matchedCtx ) {
+      console.log( chalk.bold.yellow( `\n\nSkipping a refetch of your GCP context and credentials\n\n` ) )
+      process.exit( 0 )
+    }
+
+    console.log( chalk.bold.red( `\n\nYour GCP context and credentials do NOT match - this could be bad!\n\n` ) )
+    process.exit( 1 )
+  }
+
+  console.log( `\n\nExecuting: ${cmd}\n\n` )
+  exec( `${cmd}`, ( error, out ) => {
+    if ( error ) {
+      console.log( `\n\n***ERROR ${error}\n\n` )
+      process.exit( 1 )
+    }
+  } )

package/src/packleate/Packleator.js

@@ -0,0 +1,271 @@
+const exec = require( 'child_process' ).exec
+const fs = require( 'fs-extra' )
+const path = require( 'path' )
+const async = require( 'async' )
+const copy = require( 'recursive-copy' )
+const ora = require( 'ora' )
+const tar = require( 'tar' )
+const semver = require( 'semver' )
+
+
+class Packleator {
+
+  static PRIVATE_PACKAGES_DIRECTORY = 'private_packages'
+
+  constructor( options ) {
+    const { args } = options
+    this.privatePackages = new Set()
+
+    this.args = args ? {
+      ...args,
+      output : args.output.substr( -1 ) === '/' ? args.output.substr( 0, args.output.length ) : args.output
+    } : {} // args || {}
+    this.spinner = ora( { text : 'Installing NPM dependencies...', spinner : 'monkey' } )
+    this.stderr = ''
+
+    this.tarredVersions = {}
+
+    this.outputPackageJson = {}
+    this.outputPackageLockJson = {}
+  }
+
+  async run() {
+    try {
+      this.spinner.start()
+      await this.npmInstall()
+
+      this.spinner.text = 'Copying files...'
+      await this.copyFiles()
+
+      process.chdir( this.args.output )
+
+      this.outputPackageJson = await this.getPackageJson()
+      this.outputPackageLockJson = await this.getPackageJson( undefined, true )
+    
+      this.spinner.text = 'Parsing private dependencies...'
+      const deps = await this.getPrivateDeps()
+
+      this.spinner.text = 'Packaging modules...'
+      async.eachOfSeries( deps, async ( item, key ) => {
+        const packageJson = await this.getPackageJson( item )
+        const { name, version } = packageJson
+
+        await this.pack( name, version, item )
+      }, async ( err ) => {
+        await this.rebuildPackageJson()
+        await this.rebuildPackageLockJson()
+
+        await fs.writeFile( 'package.json', JSON.stringify( this.outputPackageJson, null, 2 ) )
+        await fs.writeFile( 'package-lock.json', JSON.stringify( this.outputPackageLockJson, null, 2 ) )
+
+        await fs.remove( 'node_modules' )
+
+        const { name, version } = this.outputPackageJson
+        const fileName = `${name.replace( '@', '' ).replace( '/', '-' )}-${version}.tgz`
+
+        process.chdir( '..' )
+
+        this.spinner.text = 'Packaging results...'
+        await tar.c( {
+          file : fileName,
+          strict : true,
+          prefix : 'package/',
+          C : this.args.output
+        }, [ '.' ] )
+
+        this.spinner.text = 'Cleaning up...'
+        await this.cleanup()
+
+        this.spinner.stop()
+      } )
+    } catch ( ex ) {
+      this.spinner.stop()
+      throw ex
+    }
+  }
+
+  async rebuildPackageJson() {
+    const packageJson = this.outputPackageJson
+    const tarredPackages = Object.keys( this.tarredVersions )
+    const { dependencies = {}, devDependencies = {} } = packageJson
+
+    tarredPackages.forEach( ( tarredPackage ) => {
+      if ( dependencies[tarredPackage] ) {
+        const version = semver.maxSatisfying( this.tarredVersions[tarredPackage], dependencies[tarredPackage] )
+
+        if ( version != null ) {
+          packageJson.dependencies[tarredPackage] = `file:${Packleator.PRIVATE_PACKAGES_DIRECTORY}${path.sep}${tarredPackage.replace( '@', '' ).replace( '/', '-' )}-${version}.tgz`
+        }
+      }
+
+      if ( devDependencies[tarredPackage] ) {
+        const version = semver.maxSatisfying( this.tarredVersions[tarredPackage], devDependencies[tarredPackage] )
+
+        if ( version != null ) {
+          packageJson.devDependencies[tarredPackage] = `file:${Packleator.PRIVATE_PACKAGES_DIRECTORY}${path.sep}${tarredPackage.replace( '@', '' ).replace( '/', '-' )}-${version}.tgz`
+        }
+      }
+    } )
+
+  }
+
+  async rebuildPackageLockJson() {
+    const packageLockJson = this.outputPackageLockJson
+    const tarredPackages = Object.keys( this.tarredVersions )
+
+    const recurseDeps = ( deps ) => {
+      Object
+        .keys( deps )
+        .forEach( ( key ) => {
+          const dep = deps[key]
+
+          tarredPackages.forEach( ( tarredPackage ) => {
+            if ( key === tarredPackage ) {
+              dep.version = `file:${Packleator.PRIVATE_PACKAGES_DIRECTORY}${path.sep}${key.replace( '@', '' ).replace( '/', '-' )}-${dep.version}.tgz`
+              delete dep.resolved
+              delete dep.integrity
+            }
+
+            if ( dep.requires && dep.requires[tarredPackage] ) {
+              delete dep.requires[tarredPackage]
+            }
+          } )
+
+          if ( dep.dependencies ) {
+            recurseDeps( dep.dependencies )
+          }
+        } )
+    }
+
+    recurseDeps( packageLockJson.dependencies )
+  }
+
+  async copyFiles() {
+    const startsWith = new RegExp( `^(dist|lib|image|package|${this.args.output})` )
+    const endsWith = /\.tgz$/
+    await fs.remove( this.args.output )
+    await fs.mkdirp( this.args.output )
+    await copy( '.', this.args.output, {
+      overwrite : true,
+      dot : true,
+      filter : ( item ) => {
+        if ( item === 'package.json' || item === 'package-lock.json' ) {
+          return true
+        }
+
+        if ( startsWith.test( item ) || endsWith.test( item ) ) {
+          return false
+        }
+
+        if ( item.startsWith( '.' ) && item.indexOf( '.babelrc' ) === -1 ) {
+          return false
+        }
+
+        if ( this.args.ignore.length > 0 ) {
+          return this.args.ignore.indexOf( item ) === -1
+        }
+
+        return true
+      }
+    } )
+  }
+
+  async pack( name, version, dir ) {
+    const fileName = `${name.replace( '@', '' ).replace( '/', '-' )}-${version}.tgz`
+
+    await tar.c( {
+      file : fileName,
+      C : dir,
+      strict : true,
+      prefix : 'package/'
+    }, [ '.' ] )
+
+    await fs.move( path.join( process.cwd(), fileName ), path.join( process.cwd(), Packleator.PRIVATE_PACKAGES_DIRECTORY, fileName ), { overwrite : true } )
+
+    if ( this.tarredVersions[name] ) {
+      this.tarredVersions[name].push( version )
+    } else {
+      this.tarredVersions[name] = [ version ]
+    }
+
+    return fileName
+  }
+
+  async cleanup() {
+    await copy( this.args.output, process.cwd(), {
+      overwrite : true,
+      filter : '*.tgz'
+    } )
+    await fs.remove( this.args.output )
+  }
+
+  async npmInstall( dir = process.cwd() ) {
+    const currentDir = process.cwd()
+
+    return new Promise( ( resolve, reject ) => {
+      if ( currentDir !== dir ) {
+        process.chdir( dir )
+      }
+
+      const npmInstall = exec( 'npm install' )
+
+      npmInstall
+        .stderr
+        .on( 'data', ( data ) => {
+          this.stderr += data.toString()
+        } )
+
+      npmInstall.on( 'exit', ( code ) => {
+        if ( currentDir !== dir ) {
+          process.chdir( currentDir )
+        }
+        resolve()
+      } )
+
+      npmInstall.on( 'error', ( err ) => {
+        if ( currentDir !== dir ) {
+          process.chdir( currentDir )
+        }
+        reject( err )
+      } )
+    } )
+  }
+
+  async getPrivateDeps( depth ) {
+    return new Promise( ( resolve, reject ) => {
+
+      const depthArg = depth != null ? ` --depth ${depth}` : ''
+      exec( `npm ls --parseable --silent${depthArg}`, ( err, stdout, stderr ) => {
+        if ( err && !stdout ) {
+          reject( err )
+          return
+        }
+
+        const dependencies = stdout.split( '\n' )
+
+        if ( dependencies ) {
+          resolve( dependencies.filter( ( item ) => { 
+            const parts = item.split( path.sep )
+            return this.args.namespaces.indexOf( parts[parts.length - 2] ) !== -1
+          } ) )
+        } else {
+          reject( new Error( 'Unable to resolve package.json dependencies' ) )
+        }
+      } )
+    } )
+  }
+
+  async getPackageJson( dir = process.cwd(), lock = false ) {
+    const lockModifier = lock ? '-lock' : ''
+    try {
+      const file = await fs.readFile( path.join( dir, `package${lockModifier}.json` ), 'utf-8' )
+      const json = JSON.parse( file )
+
+      return json
+    } catch ( ex ) {
+      throw new Error( 'Error getting package.json. Make sure the current directory contains a valid package.json file' )
+    }
+  }
+}
+
+module.exports = Packleator

package/src/packleate/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+const commandLineArgs = require( 'command-line-args' )
+const commandLineUsage = require( 'command-line-usage' )
+const path = require( 'path' )
+const Packleator = require( './Packleator' )
+const ansiLogo = require( './logo-ansi' )
+
+const defaultConfig = {
+  namespaces : [ '@leverege' ],
+  output : 'lev_dest'
+}
+
+const sections = [
+  {
+    content : ansiLogo,
+    raw : true
+  },
+  {
+    content : 'Bundles private/proprietary npm packages and source code into a tarball for distribution'
+  },
+  {
+    header : 'Options',
+    optionList : [
+      {
+        name : 'output',
+        alias : 'o',
+        description : 'The destination folder (optional)',
+        defaultValue : 'lev_dest'
+      },
+      {
+        name : 'ignore',
+        alias : 'i',
+        description : 'List of files or folders to ignore. Uses glob pattern matching (optional)',
+        multiple : true
+      },
+      {
+        name : 'namespaces',
+        alias : 'n',
+        description : 'List of npm namespaces to be considered private/proprietary (optional)',
+        multiple : true
+      },
+      {
+        name : 'verbose',
+        alias : 'v',
+        description : 'Log a little bit louder now'
+      },
+      {
+        name : 'help',
+        description : 'Print this usage guide.'
+      }
+    ]
+  }
+]
+
+const usage = commandLineUsage( sections )
+
+const optionDefinitions = [
+  { name : 'output', alias : 'o', type : String, defaultValue : defaultConfig.output },
+  { name : 'ignore', alias : 'i', type : String, multiple : true, defaultValue : [] },
+  { name : 'namespaces', alias : 'n', type : String, defaultValue : defaultConfig.namespaces },
+  { name : 'verbose', alias : 'v', type : Boolean, defaultValue : false },
+  { name : 'help', type : Boolean }
+]
+
+const args = commandLineArgs( optionDefinitions )
+
+async function main() {
+  if ( args.help ) {
+    console.log( usage )
+  } else {
+    const packleator = new Packleator( { ...defaultConfig, args } )
+
+    if ( args.verbose ) {
+      console.log( packleator.args )
+    }
+
+    try {
+      await packleator.getPackageJson()
+      await packleator.run()
+    } catch ( ex ) {
+      console.error( ex.message )
+    }
+  }
+}
+
+main()

package/src/packleate/logo-ansi.js

@@ -0,0 +1,16 @@
+module.exports = 
+`    .    . .    .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .  .  . . 
+  .   . S%  .     .       .       .       .       .       .       .       .       .       .       .       .       .       .       .       .     .     
+    .  .:% : .  .    . ..    . . . .  .    ...... . ... ..   . .  . .. .. . ..... .  .... . .. .    ..... . ... .   ..... . .. .  . ..... . . .    .  
+  .      :88:..    .  . .8:   . .8. .   .. @8X@@@@@@8% @88X .   . tX8% 888@@@@@@@@t. t8@@@@@%;% . . @8@@@@@@@8%.  .. ;t%88t@.   .:X8@@@@@@@88 .  .   .
+     . .. 8888:.    . .X8S .  . S%     . . :S@;ttttt%. St%8..   . @S;@ XX8S:tttttt@  8SS;tttS88 X.. ;SX;ttttt% . ..t @8tttX88 t. t@@S:t%%ttSt .    .  
+  .      . @8888;.  :t @8;.  .  @@       . .8SS:;:;:: . 8SS. . . ;8@@. X88@.;:;:;. . X@:;::;.;X8t%. .8SX:;:;::  .% 8::t;:: S S . tSXt.;;:;:.   .      
+    .        888; .t8 .X:.    . XS@   .  . :XSt .    . . S8SS . :.%X : @@88 .    . . @S .   . 8888  :XS; .    .. @@@8..    ....  t%S:..    . .   .  . 
+  .   .  . ..888StS 8: ... .  . @@      .. :X@       t ..%;t@.. ;@.S . X88;.    .8 : X@.: ...t8X.t. :@@       S ..S8..  .   %X;  tX8;.    .  . .   .  
+    .      . t8888X %8t .    .. @SX .    . :XX ;;;;:t:  ..8S@:.X888 .. X88S::;;;.% . @X@%S;%X8X@X . :@t;;;;;:;;. %@ ..   ..  %t. t%X8;:;;; 8..   .    
+  .    . .  .:88Xtt88     .   . @X   ..... :XSS..:..:..  . @X;: SS . . X88@ ::.:.. . @XX@X@@S@t ... .@@S ::..:.. ;88t ..... SX:  tSX; ::.:...       . 
+     .       . :8888%       . . @X S8@@8@: :XS8X@X@X@X:  . %;8 @%X . . @88:S@X@X@@;. @X . ..8X8; .. :XS8S@X@X@@:  t88 t8%S8:;t:  t%XSX@@X@X@% .  .    
+  .    .  . . . :X8@.:     .  . 88X8@888SS .8@@8888@888.. ..8S@X8 .  . @8@@88888@8;  S8 . . .@.8St. .8@888888888...% S%888Xt@t; .;%8888888@@8 .   .  .
+    .            8 :..          .;;:::;::. :;;::::;:;:.     .:;.       .;:;::;::::.  .;:   .  .:;:  :;::::::::::   . ..:t;:: .   :%;;:::::::.  .      
+  .   . .  .  .  X%          .       . .     .  . .  .  .    . .  .  .    . . . . .  .   .   .        . . . ..      .    .  .  .     . . .. .    . .  
+    .            .. .         . .  .    .  .     .    .   .     .      .         .     .       . .  .  .   .     .    .    .           .      .      .`