@suffolklitlab/alkiln 5.13.0-logs3 → 5.13.1

package/lib/utils/log.js

@@ -1,489 +1,96 @@
-const fs = require(`fs`);
-const util = require(`node:util`);
-const session_vars = require( `./session_vars` );
-const time = require(`./time`);
-const files = require(`./files`);
+const fs = require('fs');
+const session_vars = require( './session_vars' );
 
-// ? 🌈 💡 🔎 🤕 🐛
+// ? 🌈 💡 🔎 🤕 🐞
 // Alternatives: 🩹 ❤️‍🩹 🚑
 // TODO: return full message so it can be passed to manually
 // thrown errors if needed.
 
-/**
- * TODO:
- * - [x] Store log filename in runtime_config
- * - [x] `types` -> `context`
- * - [x] Remove "cosmetic"/"plain" logs and just work that beauty into the logs themselves
- * - [ ] Save logs from GitHub actions as well
- * - [ ] Capture cucumber ProgressFormatter logs instead of making them ourselves?
- * - [ ] Write user errors and warnings (sent to .console()) to unexpected results file
- * - [ ] Write debug errors and warnings to unexpected results file?
- * - [ ] write tests...?
- * - [ ] Edit the decision doc? Too many individual decisions? Use separate docs instead?
- *    - streams vs. formatter vs. fs.appendFileSync
- *    - general architecture?
- *    - keeping report separate for now
- *    - try/catching everything + collecting errors
- *    - `throw` (non-standard) (throw errors in logs? (bad stack trace) 2 lines everywhere instead?)
- *    - `success` (non-standard)
- *    - `before` option and no others? (others can be included in message, but no way to log before the code otherwise.)
- *    - Name "debug" meaning change instead of "verbose"
- * */
-//
+let log = {};
+module.exports = log;
 
-class Log {
-  /** Handles logging to the console, saving to files and reports,
-   *  and throwing errors.
-   *
-   * Use this to:
-   * - Log to the console
-   * - Save to the debug log
-   * - Throw errors with log codes and other info
-   * - Log without new lines
-   *
-   * What are the different log files:
-   * - report is a pretty file that is only complete at the end of all tests
-   * - report_log is not pretty, but has the same info as the report in case tests end early
-   * - debug_log is very ugly and has notes for developers
-   *
-   * TODO:
-   * - Save to the report and report log
-   *
-   * @params
-   * options { object }
-   * options.path { str } - Optional. The path where the final logs
-   *  should be stored.
-   * options.context { str } - Optional. Info about what's creating
-   *  this Log.
-   *
-   * We're not using console.Console or write streams because we can't
-   * control their life cycle in steps.js. We can't tell when to
-   * properly flush and end the stream in the case of a sudden failure.
-   * */
-
-  report_filename = `report.txt`;
-  report_log_filename = `report_log.txt`;
-  debug_log_filename = `debug_log.txt`;
-  unexpected_filename = `unexpected_results.txt`;
-
-  constructor({ path, context } = {}) {
-    // this.id = uuid();
-
-    // Make sure folder exists
-    if ( path ) { files.make_artifacts_folder( path ); }
-    // In local development and ALKilnInThePlayground, this will
-    // mostly be called by the `run` command.
-    else { path = files.make_artifacts_folder(); }
-
-    this.path = path;
-    session_vars.save_artifacts_path_name( this.path );
-
-    if ( context ) { context = context + ` log`; }
-    else { context = `log`; }
-    this.info({ code: `ALK0215`, context, },
-      `Saving files to "${ this.path }"`
-    );
-  }
-
-  console( console_opts = {}, ...logs ) {
-    /** Log the logs to the console at the right level and with the metadata.
-     * Return the start of the message - the part without the logs
-     *
-     * Questions:
-     * - Allow `logs` to be a string?
-     * - Allow `context` to be a space-separated string?
-     * - Throw errors? Need to manipulate call stack.
-     * - Turn logs that are non-strings into `JSON.stringify`d strings?
-     * - Should every log be able to have an error? To keep the
-     *   signature consistent.
-     *
-     * @examples:
-     * Log = require('./lib/utils/log.js');
-     * log = new Log('_alkiln-');
-     *
-     * log.console();
-     * // * ALK000c console LOG [2024-08-16 00:30:39UTC]:
-     *
-     * log.console({
-     *   level: 'info',
-     *   icon: '&',
-     *   code: 'ALK00t1',
-     *   context: 'a test',
-     * }, 'test info log');
-     *
-     * try {
-     *   let czar = zoo + 5;
-     * } catch ( error ) {
-     *   log.console({
-     *     level: 'error',
-     *     before: '===\n===\n',
-     *     icon: 'X'
-     *     code: 'ALK00t2'
-     *     context: 'err_test'
-     *     error: new Error('This is an error'),
-     *   }, 'error test log 1', 'error test log 2')
-     * }
-     * */
-
-    let {  // Defaults
-      level = `log`,
-      before =  ``,  // different name? above? start_decorator?
-      icon = `*`,
-      code = `ALK000c`,
-      context = ``,
-      error = null,
-      do_throw = false,
-    } = console_opts;
-
-    let with_error = [...logs];
-    if ( error ) {
-      with_error.push( error );
-    }
-
-    let formatted_log = this.debug({ level, before, icon, code, context }, ...with_error );
-    // Shame to do this in .debug too, but haven't found a
-    // better way to return consistent values otherwise. We
-    // want other logs to be logged by the console in its way.
-    const metadata = this._format_metadata({ level, icon, code, context });
-
-    // Throw whatever we can throw
-    if ( do_throw ) {
-      let custom_msg = this._stringify_logs({ logs: [ metadata, ...logs ] });
-      // TODO: Save to unexpected results file
-      if ( error instanceof Error ) {
-        console.log( before + custom_msg );
-        throw error;
-      } else if ( error !== null ) {
-        console.log( before + custom_msg );
-        throw new Error( error );
-      } else {
-        console.log( before ); // Adds extra new line, unfortunately
-        throw new Error( custom_msg );
-      }
-    }
-
-    try {
-      // Otherwise, log at the given level if console has that method (`log` by default)
-      // If a non-standard level was passed in, like `success`, use `info` by default
-      if ( console[ level ]) {
-        // TODO: Save `warn` to unexpected results file
-        console[ level ]( before + metadata, ...with_error );
-      } else {
-        console.info( before + metadata, ...with_error );
-      }
-    } catch ( console_log_error ) {
-      // Fail silently, gather errors
-      try {
-        this.debug({
-          level: `warn`, icon: `🔎`, code: `ALK0211`,
-          context: `internal`,
-          error: console_log_error
-        }, `Skipped saving a ${ level } message to the debug log`);
-      } catch ( console_debug_error ) {
-        console.warn( `🔎 ALK0217 internal WARNING: Skipped the same log two times consecutively`, console_debug_error, console_log_error );
-      }
-    } finally {
-      return formatted_log;
-    }
-  }
-
-  debug( debug_opts = {}, ...logs ) {
-    /** Save in the debug log file and return a string version
-     *  of the log. If there are errors, just log them too.
-     *  Keep as much info from the caller as possible. Avoid throwing
-     *  errors if at all possible while giving the max info possible.
-     *  Avoid logging to the visible console.
-     *
-     * TODO: Log warning with stack trace
-     *
-     * @examples:
-     *
-     * Log = require('./lib/utils/log.js')
-     * log = new Log({ path: '_alkiln-' })
-     * log.debug()
-     * // 🐛 ALK000v debug DEBUG [2024-08-16 00:38:49UTC]:
-     * */
-    let {
-      level=`debug`,
-      before = ``,
-      icon = `🐛`,
-      code = `ALK000v`,
-      context = ``,
-      error = null,
-    } = debug_opts;
-
-    // function stackTrace() { return (new Error()).stack; }
-    // and
-    // https://stackoverflow.com/a/41820537/14144258
-    // var mystring=require('util').inspect(error_object);
-
-    let logging_errors = [];
-
-    // Get a proper error log if needed
-    if ( level === `throw` ) { level = `error`; }
-
-    let metadata = `No metadata: `;
-    try {
-      metadata = this._format_metadata({ level, icon, code, context });
-    } catch ( metadata_error ) {
-      // Consider using `util.inspect()` for the error
-      logging_errors.push(`🔎 ALK0212 internal WARNING: Skipped creating debug metadata\n${ metadata_error.stack }`);
-    }
-
-    // Include error as the last log
-    let with_error = [...logs];
-    if ( error ) {
-      with_error.push( error );
-    }
-
-    let formatted_log = `${ metadata }No formatted log.`;
-    try {
-      let stringified = this._stringify_logs({ logs: with_error });
-      formatted_log = `${ before }${ metadata }${ stringified }`;
-    } catch ( formatted_log_error ) {
-      // Consider using `util.inspect()` for the error
-      logging_errors.push(`🔎 ALK0213 internal WARNING: Skipped creating full debug log\n${ formatted_log_error.stack }`);
-    }
-
-    let fs_append_failed = false;
-    try {
-      fs.appendFileSync( `${ this.path }/${ this.debug_log_filename }`, `\n` + formatted_log )
-    } catch ( fs_append_error ) {
-      fs_append_failed = true;
-      // Consider using `util.inspect()` for the error
-      logging_errors.push(`🔎 ALK0214 internal WARNING: Could not append to debug log file\n${ fs_append_error.stack }`);
-    }
-
-    // Record any errors in the most unobtrusive way possible
-    if ( logging_errors.length > 0 ) {
-      for ( let logging_error of logging_errors ) {
-        if ( fs_append_failed ) {
-          console.warn( logging_error );
-        } else {
-          // TODO: Log warning with stack trace
-          fs.appendFileSync( `${ this.path }/${ this.debug_log_filename }`, `\n` + logging_error.stack );
-        }
-      }
-    }
-
-    return formatted_log;
-  }
-
-  _format_metadata( metadata_opts = {} ) {
-    /** Format and return the log metadata.
-     *  Example: "💡 ALK#### internal INFO [10:24:40 pm UTC]: "
-     * */
-    let {
-      level=`log`,
-      icon = `?`,
-      code = `ALK000m`,
-      context = ``,
-    } = metadata_opts;
-
-    let metadata = `? ALK000m unspecified: `;
-    try {
-      let metadata_level = level;
-      if ( level === `warn` ) { metadata_level = `warning`; }
-      let level_caps = metadata_level.toUpperCase();
-      // For elapsed time, see https://nodejs.org/api/console.html#consoletimelabel
-      // Should this really be a pretty date, or should it be a raw timestamp?
-
-      // let metadata_list = [ icon, code, context, level_caps, `[${ time.log_date() }]` ];
-      // let metadata_list = [ icon, code, context, level_caps, `[${ time.log_date() }]` ].filter(function ( item ) {
-      //   return item !== ``;
-      // }).join(` `) + `: `;
-
-      let metadata_list = [];
-      for ( let item of [ icon, code, context, level_caps, `[${ time.log_date() }]` ]) {
-        if ( item !== `` ) { metadata_list.push(item); }
-      }
-      metadata = metadata_list.join(` `) + `: `;
-    } catch ( metadata_error ) {
-      let msg = `Skipped creating metadata`;
-      code = `ALK0220`;
-      icon = `🔎`;
-      context = `internal logs metadata`;
-      try {
-        this.debug({ icon, level: `warn`, code, context, error: metadata_error }, msg );
-      } catch {
-        console.warn( `${ icon } ${ code } ${ context } WARNING [${ Date.now() }]: ${ msg }`, metadata_error );
-      }
-    }
-    return metadata;
+let create_msg_start = function ( types, pre='', code=`? ALK0000` ) {
+  // ? - unknown (fallback)
+  let types_str = types.join(` `);
+  if ( types_str.includes(`plain`) ) {
+    return pre;
+  } else {
+    return `${ code } ${ types_str }: ${ pre }`;
   }
-
-  _stringify_logs(str_log_opts = {}) {
-    /** Return a string - a formatted version of the list
-     *  of logs by stringifying non-strings. An empty list
-     *  or no argument is valid. */
-
-    let { logs = [] } = str_log_opts;
-
-    let stringified_logs = ``;
-    let prev_line_type = null;
-
-    try {
-      for ( let log of logs ) {
-        // TODO: Try/catch each of these?
-        if ( log === null || [`string`, `number`, `undefined`, `boolean`].includes( typeof(log) )) {
-
-          stringified_logs += this._stringify_inline({ prev_line_type, log });
-          prev_line_type = `inline`;
-
-        } else {
-          // For objects and errors
-          stringified_logs += this._stringify_object({ obj: log });
-          prev_line_type = `block`;
-        }  // ends typeof log
-      }  // Ends for logs
-    } catch ( stringify_error ) {
-      try {
-        // TODO: Should `stringify_error` get recorded even when util.inspect works?
-        stringified_logs = util.inspect( logs, { depth: 8, maxArrayLength: null, maxStringLength: null, });
-      } catch ( util_error ) {
-
-        if ( stringified_logs ) {
-          stringified_logs += `Unable to stringify logs. Got:\n${ stringified_logs }\n${ util_error.stack }\n${ stringify_error.stack }`;
-        } else {
-          stringified_logs = `Unable to stringify logs.\n${ util_error.stack }\n${ stringify_error.stack }`;
-        }
-      }
-    }
-
-    return stringified_logs;
-  }  // Ends Log._stringify_logs()
-
-  _stringify_inline({ prev_line_type, log }) {
-    /** Format an inline log. Mostly involves fiddling with
-     *  the start of the string. */
-    // An inline log's string starts with nothing if it's the first string...
-    let start = ``;
-    // ...starts after a space if its next to an inline string...
-    if ( prev_line_type === `inline` ) { start = ` `; }
-    // ...or starts on a new line if it's after a block of text,
-    // like an error or object.
-    else if ( prev_line_type === `block` ) { start = `\n`; }
-    return `${ start }${ log }`;
-  }
-
-  _stringify_object({ obj }) {
-    /** Try to stringify an object a few different ways. Works for
-     *  errors too. */
-    try {
-      // A block of text (the object) always starts on a new line
-      // Try to stringify the object.
-      return `\n${ util.inspect( obj, { depth: 8, maxArrayLength: null, maxStringLength: null, } )}`;
-    } catch ( outer_error ) {
-      // If that fails, see if it has its own way of stringifying
-      // TODO: record these errors?
-      try {
-        return `\n${ obj }`;
-      } catch ( inner_error ) {
-        // Lastly, give at least some information
-        return `\nUnable to log this ${ typeof obj }`;
-      }  // ends inner try
-    }  // ends outer try
-  }
-
-  success( success_opts = {}, ...logs ) {
-    /** Console log success - log level with success icon. */
-    // Discuss: do we want to log some successes as "💡 ... SUCCESS: "?
-    // Should we allow callers to override levels and icons?
-    let {
-      code = `ALK000s`, before = ``, context = ``
-    } = success_opts;
-    return this.console({
-      level: `success`, icon: `🌈`,
-      before, code, context,
-    }, ...logs);
-  }
-
-  info( info_opts = {}, ...logs ) {
-    /** Console log info. */
-    let {
-      code = `ALK000i`, before = ``, context = ``,
-    } = info_opts;
-    return this.console({
-      level: `info`, icon: `💡`,
-      before, code, context,
-    }, ...logs);
-  }
-
-  warn( warning_opts = {}, ...logs ) {
-    /** Console log warning. */
-    let {
-      code = `ALK000w`, before = ``, context = ``
-    } = warning_opts;
-    return this.console({
-      level: `warn`, icon: `🔎`,
-      before, code, context,
-    }, ...logs);
-  }
-
-  throw( throw_opts = {}, ...logs ){
-    /** Console log and throw error.
-     *  The `error` option is required. */
-    let {
-      code = `ALK000t`, before = ``, context = ``,
-      do_throw = true, error,
-    } = throw_opts;
-    return this.console({
-      level: `error`, icon: `🤕`,
-      before, code, context, error,
-    }, ...logs);
-  }
-
-  unexpected({ text = `` } = {}) {
-    /** TODO: Save to the unexpected results file. (Errors, maybe warnings) */
-    fs.appendFileSync(`${ this.path }/${ this.unexpected_filename }`, `\n${ text }` );
-  }
-
-  stdout(stdout_opts = {}, ...logs) {
-    /** Prints in the console inline and saves to the debug log
-     *  and the report log.
-     *
-     * @params
-     * options { obj }
-     * options.records_only { bool } - Whether to only save logs
-     *  without printing them to the console. E.g. progress
-     *  summary characters like those that cucumber is already
-     *  printing to the console.
-     * */
-    let {
-      records_only = false,
-    } = stdout_opts;
-    let whole_log = logs.join(` `);
-
-    // Write to the debug and report files
-    this._record_stdout({ logs });
-
-    if ( !records_only ) {
-      process.stdout.write( whole_log );
-    }
-
-    return logs;
-  }
-
-  _record_stdout({ logs = [] }) {
-    /** Save stdout output to various debug and report files. */
-    this.debug({ code: `ALK0219`, context: `stdout` }, ...logs);
-    let whole_log = logs.join(` `);
-    fs.appendFileSync( `${ this.path }/${ this.report_log_filename }`, whole_log );
-    // TODO: write to report after report metadata
+};
+
+// Where is this used?
+log.success = function ({ type='', pre='', data='', post='', code=`ALK0000` }) {
+  /** Log success msg with the given information and strings, prepended with `ALKiln`.
+   *  `type` is often something like 'setup', 'takedown', etc. */
+  // √ - info (fallback)
+  let start = create_msg_start([ type, `SUCCESS` ], pre, `🌈 ${code}` );
+  // Log them each on a separate line
+  console.info( `${ start }` );
+  if ( data ) { console.info( data ); }
+  if ( post ) { console.info( post ); }
+};
+
+// Where is this used?
+log.info = function ({ type='', pre='', data='', post='', code=`ALK0000` }) {
+  /** Log info msg with the given information and strings, prepended with `ALKiln`.
+   *  `type` is often something like 'setup', 'takedown', etc. */
+  // & - info (fallback)
+  let start = create_msg_start([ type, `INFO` ], pre, `💡 ${code}` );
+  // Log them each on a separate line
+  console.info( `${ start }` );
+  if ( data ) { console.info( data ); }
+  if ( post ) { console.info( post ); }
+};
+
+// Where is this used?
+log.warn = function ({ type='', pre='', data='', post='', code=`ALK0000` }) {
+  /** Log warning msg with the given information and strings, prepended with `ALKiln`.
+   *  `type` is often something like 'setup', 'takedown', etc. */
+  // ! - warning (fallback)
+  let start = create_msg_start([ type, `WARNING` ], pre, `🔎 ${code}` );
+  // Log them each on a separate line
+  console.warn( `${ start }` );
+  if ( data ) { console.warn( data ); }
+  if ( post ) { console.warn( post ); }
+};
+
+// Where is this used?
+log.error = function ({ type='', pre='', data='', post='', code=`ALK0000` }) {
+  /** Log error msg with the given information and strings, prepended with `ALKiln`.
+   *  `type` is often something like 'setup', 'takedown', etc. */
+  // X - error (fallback)
+  let start = create_msg_start([ type, `ERROR` ], pre, `🤕 ${code}` );
+  // Log them each on a separate line with extra new lines around the whole thing
+  console.error( `\n${ start }` );
+  if ( data ) { console.error( data ); }
+  if ( post ) { console.error( post, `\n` ); }
+};
+
+log.debug = function ({ type='', pre='', data='', post='', verbose=false, code=`ALK0000` }) {
+  /** If debugging is turned on, log a message that includes `ALKiln` and `debug` */
+  // @ - debug (fallback)
+  let start = create_msg_start([ type, `DEBUG` ], pre, `🐞 ${ code }` );
+  let full = `\n${ start }`;
+  if ( data ) { full += `\n${ data }`; }
+  if ( post ) { full += `\n${ post }`; }
+
+  // TODO: Make a verbose log instead of adding to the debug one and always add to it
+  if ( verbose ) {
+    log.add_to_debug_log( full );
   }
 
-  clear() {
-    /** Empty all files possible. Mostly for testing. */
-    try { fs.writeFileSync( `${ this.path }/${ this.debug_log_filename }`, `` ); }
-    catch (error) { /* Do nothing, no file there or something */ }
-    try { fs.writeFileSync( `${ this.path }/${ this.report_log_filename }`, `` ); }
-    catch (error) { /* Do nothing, no file there or something */ }
-    try { fs.writeFileSync( `${ this.path }/${ this.report_filename }`, `` ); }
-    catch (error) { /* Do nothing, no file there or something */ }
-    try { fs.writeFileSync( `${ this.path }/${ this.unexpected_filename }`, `` ); }
-    catch (error) { /* Do nothing, no file there or something */ }
+  if ( session_vars.get_debug() ) {
+    // Log them each on a separate line
+    console.log( `\n${ start }` );
+    console.log( data );
+    console.log( post );
   }
+};
 
-}  // Ends Log{}
+log.add_to_debug_log = function(value) {
+  fs.appendFileSync(log.debug_log_file, value);
+};
 
-module.exports = Log;
+log.debug_log_file = `debug_log.txt`;
+log.unexpected_filename = `unexpected_results.txt`;

package/lib/utils/reports.js

@@ -66,20 +66,14 @@ reports.addToReport = function( scope, { type, code, value }) {
   const MISC_ARTIFACTS_DIR = `_alkiln-misc_artifacts`;
   if ( !scope.paths ) {
     // Can this be usefully abstracted?
-    let date = files.readable_date();
-    scope.paths = {
-      debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_debug_log-${ date }.txt`,
-      report_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_report_log-${ date }.txt`,
-    };
+    scope.paths = { debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_logs-${ files.readable_date() }.txt` };
   }
 
   try {
     fs.appendFileSync( scope.paths.debug_log, `\nReport:\n${debug_line}` );
-    fs.appendFileSync( scope.paths.report_log, `\nReport:\n${debug_line}` );
-  } catch ( file_error ) {
+  } catch ( err ) {
     fs.mkdirSync( MISC_ARTIFACTS_DIR );
     fs.appendFileSync( scope.paths.debug_log, `\nReport:\n${debug_line}` );
-    fs.appendFileSync( scope.paths.report_log, `\nReport:\n${debug_line}` );
     // An error in here should throw (for now)
   }
 
@@ -140,9 +134,6 @@ reports.saveFinalScenarioData = function( scope, { status=`in progress` }) {
   return scenario;
 };  // Ends reports.saveFinalScenarioData()
 
-reports.progress = function ({ logs=[] }) {
-  // TODO: save stdout-style to report_log, object, and getting printable scenario
-};
 
 reports.setReportScenarioStatus = function( scope, { status=`PASSED` }) {
   /** Add final status of scenario to scenario report object - passed, failed, etc. */
@@ -212,7 +203,7 @@ reports.getPrintableScenario = function( scenario ) {
   return report;
 };  // Ends reports.getPrintableScenario()
 
-let getLineText = function ({ type=`no type`, code=`ALK00rl`, value=`` }) {
+let getLineText = function ({ type=`no type`, code=`ALK0000`, value=`` }) {
   let start = ``;
   if ( type.includes(`page_id`) ) { start += `screen id: `; }
   else if ( type.includes(`outcome`) ) { start += `\n`; }  // extra new line
@@ -221,7 +212,7 @@ let getLineText = function ({ type=`no type`, code=`ALK00rl`, value=`` }) {
   return `${ start }${ value }`;
 };  // Ends getLine()
 
-let getDebugLine = function ({ type=``, code=`ALK00rd`, value=`` }) {
+let getDebugLine = function ({ type=``, code=`ALK0000`, value=`` }) {
   /** In debug log lines, include all the information possible. */
 
   // `plain` is usually used for visual clarity and shouldn't have