@suffolklitlab/alkiln 5.12.0 → 5.13.0-logs1

package/lib/utils/log.js

@@ -1,96 +1,489 @@
-const fs = require('fs');
-const session_vars = require( './session_vars' );
+const fs = require(`fs`);
+const util = require(`node:util`);
+const session_vars = require( `./session_vars` );
+const time = require(`./time`);
+const files = require(`./files`);
 
-// ? 🌈 💡 🔎 🤕 🐞
+// ? 🌈 💡 🔎 🤕 🐛
 // Alternatives: 🩹 ❤️‍🩹 🚑
 // TODO: return full message so it can be passed to manually
 // thrown errors if needed.
 
-let log = {};
-module.exports = log;
+/**
+ * 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 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 }`;
+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;
   }
-};
-
-// 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 );
+
+  _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
   }
 
-  if ( session_vars.get_debug() ) {
-    // Log them each on a separate line
-    console.log( `\n${ start }` );
-    console.log( data );
-    console.log( post );
+  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 */ }
   }
-};
 
-log.add_to_debug_log = function(value) {
-  fs.appendFileSync(log.debug_log_file, value);
-};
+}  // Ends Log{}
 
-log.debug_log_file = `debug_log.txt`;
-log.unexpected_filename = `unexpected_results.txt`;
+module.exports = Log;

package/lib/utils/reports.js

@@ -66,14 +66,20 @@ reports.addToReport = function( scope, { type, code, value }) {
   const MISC_ARTIFACTS_DIR = `_alkiln-misc_artifacts`;
   if ( !scope.paths ) {
     // Can this be usefully abstracted?
-    scope.paths = { debug_log: `${ MISC_ARTIFACTS_DIR }/unit_tests_logs-${ files.readable_date() }.txt` };
+    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`,
+    };
   }
 
   try {
     fs.appendFileSync( scope.paths.debug_log, `\nReport:\n${debug_line}` );
-  } catch ( err ) {
+    fs.appendFileSync( scope.paths.report_log, `\nReport:\n${debug_line}` );
+  } catch ( file_error ) {
     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)
   }
 
@@ -81,7 +87,7 @@ reports.addToReport = function( scope, { type, code, value }) {
   let scenario = reports.makeSureScenarioExists( scope );
   scenario.lines.push({ type, code, value });
 
-  return scenario;
+  return getLineText({ type, code, value });
 };  // Ends reports.addToReport()
 
 reports.create = function( scope ) {
@@ -134,6 +140,9 @@ 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. */
@@ -203,7 +212,7 @@ reports.getPrintableScenario = function( scenario ) {
   return report;
 };  // Ends reports.getPrintableScenario()
 
-let getLineText = function ({ type=`no type`, code=`ALK0000`, value=`` }) {
+let getLineText = function ({ type=`no type`, code=`ALK00rl`, value=`` }) {
   let start = ``;
   if ( type.includes(`page_id`) ) { start += `screen id: `; }
   else if ( type.includes(`outcome`) ) { start += `\n`; }  // extra new line
@@ -212,7 +221,7 @@ let getLineText = function ({ type=`no type`, code=`ALK0000`, value=`` }) {
   return `${ start }${ value }`;
 };  // Ends getLine()
 
-let getDebugLine = function ({ type=``, code=`ALK0000`, value=`` }) {
+let getDebugLine = function ({ type=``, code=`ALK00rd`, value=`` }) {
   /** In debug log lines, include all the information possible. */
 
   // `plain` is usually used for visual clarity and shouldn't have