@suffolklitlab/alkiln 5.13.4 → 5.15.0

package/lib/utils/_alkiln-constrained_random_tests_old.js

@@ -0,0 +1,1776 @@
+
+/**
+ *
+ * | var | possible_values |
+ * | favorite_color | blue;; green;; red |
+ *
+ * @param raw_var_data { [{ var, possible_values }] } List of table row objects
+ * @param raw_var_data[i].var {str} Name of the variable to set
+ * @param raw_var_data[i].possible_values {str} Format is ";;" separated
+ *    possible values for the variable (lawyers use ";" grammatically)
+ * */
+
+/** Need a sentence for:
+ * And I will go to the interview at the address ("")
+ * And I will run (100) constrained random tests
+ * And those tests should get to one of these page ids - [("lsdjf", "sldkjf")]
+ * And I will get there with random choices from this data:
+ *   | var | possible_values |
+ *   | favorite_color | blue;; green;; red |
+ *
+ * Write files
+ * 1. Make an object from the given constraints table (split by single _and_
+ *    double quotes? Just double quotes? Document author _must_ use double
+ *    quotes?)
+ * 1. Make sure that it's not the same as previous objects
+ * 1. Far in the future: Make sure it's not the same as a test the author
+ *    already wrote (need to wrap cucumber for this to run all random tests
+ *    last)
+ * 1. Make a Scenario description using the iteration number
+ * 1. Add to one big file (name includes datetime) for all these Scenarios
+ * 1. Increment iteration number
+ * 1. Leave them there to get run later
+ *
+ * Supposedly more performant to write one big file [^citation needed]. Not
+ *    sure it matters that much yet. If we do want to optimize, maybe using
+ *    a write stream directly is the way to go.
+ *
+ * Command:
+ * I run (\d*) random tests for/at "interview.yml" that will reach one of these question/page ids (\[".*"]) with these constraints: (table)
+ * (\d*) random at "interview.yml" will reach one/any of (\[.*]) with: (table)
+ *
+ * Given I generate 100 random tests
+ * And I test the interview at ""
+ * And I reach any of these question/page ids: ""
+ * And I answer with/give these possible answers: (table)
+ * I generate 100 random tests for the interview at "" to reach any of the question ids [] with these possible answers
+ *
+ */
+
+/**
+ * If not doing a 1-Scenario requirement
+ * 
+ * Find end of previous Scenario by going backwards in the list of file lines
+ * until we reach a non-comment/blank line.
+ * */
+
+/** What do I want this AST to look like?
+ * Gherkin AST does validating
+ * 
+ * {
+ *  *
+ *  feature tags str,
+ *  *
+ *  feature str,
+ *  *
+ *  scenarios: [
+ *   scenario1 tags str,
+ *   *
+ *   scenario2 str
+ *   *
+ *   steps: [
+ *    *
+ *    first step 1,
+ *    *
+ *    first step 2,
+ *    *
+ *    constraints step 1 {
+ *     ids, table
+ *     step str,
+ *     table str
+ *     (or whole thing)
+ *     (gherkin AST parser for fake file to get the table. what then?)
+ *    }
+ *    *
+ *    constraints step 2 {}
+ *    *
+ *   ]
+ *   *
+ *   scenario 2...
+ *  ]
+ * }
+ * 
+ * # or empty line = maybe_scenario_end
+ * unless we hit
+ *   Not something else that is not "Scenario:" (or tags) and `scenario end` is canceled
+ * if "Scenario:" (or tags)
+ *   From the previous maybe_scenario_end and here is the tween scenarios part
+ * 
+ * Except! If we're in quotes... how? What can be delimiters? """ or ```
+ * 
+ * 
+ * */
+
+
+const COMMENT_REGEX = /^[\s\t]*#/;
+const BLANK_LINE_REGEX = /^[\s\t]*$/;
+
+const ALKILN_REGEX = /ALKiln/i;
+const CONSTRAIN_REGEX = /constrain/i;  // constrained/constraint/constraints
+const RAND_REGEX = /rand/i;  // random/randomness/randomized
+const GENERAT_REGEX = /generat/i;  // generate/generates/generated/generating
+const MAKE_REGEX = /make|made/i;  // make/makes/made/making
+const NUMBER_REGEX = /\d+/i;
+const CAPTURE_NUMBERS_REGEX = /(\d+)/g;
+const DOULBE_QUOTES_REGEX = /"[^"]+"/;
+const SINGLE_QUOTES_REGEX = /'[^']+'/;
+
+class Parser {
+  /** step_tweens (between significant steps - fore_step, constraints_step)
+   * 
+   * Need: current type/mode/context and the current line
+   * 
+   * What's the difference between the text of a step and the stuff that comes
+   * after like a docstring or datatable
+   * 
+   * modes:
+   * - fore_step
+   * - constraints_step (do we add tween steps to the top? as long as we don't
+   *   want to use the gherkin ast parser)
+   * - constraints_table
+   * - x table_tween
+   * - doc_string
+   * - doc_string_end ("""/```)
+   * - x step_tween
+   * - non_mode (everything is a tween unless it starts a new mode)
+   * 
+   * */
+  increment(return_obj, index) { return_obj.next = index + 1; return return_obj; }
+
+  comment({ old_lines=[], index=0, new_lines=[] }) {
+    /** Add line */
+    let result = { match: false, error: null, lines: new_lines };
+    if ( COMMENT_REGEX.test(old_lines[ index ]) ) {
+      result.match = true;
+      new_lines.push(old_lines[ index ]);
+    }
+    return this.increment( result, index );
+  }
+
+  blank({ old_lines=[], index=0, new_lines=[] }) {
+    /**  */
+    let result = { match: false, error: null, lines: new_lines };
+    if ( BLANK_LINE_REGEX.test(old_lines[ index ]) ) {
+      result.match = true;
+      new_lines.push(old_lines[ index ]);
+    }
+    return this.increment( result, index );
+  }
+
+  description({ old_lines=[], index=0, new_lines=[], contexts={} }) {
+    /** Do we need this? Should we just outlaw descriptions? */
+    if ( !context.scenario ) {
+    }
+  }
+
+  num_tests_Step({ old_lines=[], index=0, new_lines=[] }) {
+    let result = { match: false, error: null, lines: new_lines };
+    let text = old_lines[ index ];
+
+    // Use `.test()` without `g` flag. See
+    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test#using_test_on_a_regex_with_the_global_flag
+    let is_num_Step = NUMBER_REGEX.test( text )
+                      && ALKILN_REGEX.test( text )
+                      &&  CONSTRAIN_REGEX.test( text )
+                          && ( RAND_REGEX.test( text )
+                               || GENERAT_REGEX.test( text )
+                               || MAKE_REGEX.test( text )
+                             );
+    if ( is_num_Step ) {
+      result.match = true;
+      results.value = { num_to_make: text.match( CAPTURE_NUMBERS_REGEX ) };
+    }
+
+    return this.increment( result, index );
+  }
+
+  constraints_Step({ old_lines=[], index=0 }) {
+    let result = { match: false, error: null };
+    let text = old_lines[ index ];
+    let step_matches = ALKILN_REGEX.test( text )
+                       && DOULBE_QUOTES_REGEX.test( text )
+                       && SINGLE_QUOTES_REGEX.test( text );
+    if ( !step_matches ) { return result; }
+
+    let table_lines = old_lines.split( index + 1 );
+    for ( let line of table_lines ) {
+      if ( this.table({ line }) ) {
+        result.matches = true;
+        result.value = { line: text };  // Maybe get ids here
+        break;
+      }
+      // Need to change signatures
+      if ( this.comment({ line }) || this.blank({ line }) ) {
+        continue;
+      } else {
+        break;
+      }
+    }
+
+    return this.increment( result, index );
+  }
+
+  table({ line, index=0 }) {
+    let result = { match: false, error: null };
+    if ( /^[\s\t]*\|/.test( line )) {
+      result.match = true;
+      result.value = { line: line };  // modify line to change header or choose unique value
+    }
+    return this.increment( result, index );
+  }
+
+  other({ old_lines=[], index=0, new_lines=[] }) {
+    /**
+     * When in between feature and scenario keyword or between scenario keyword
+     *     and steps, this is a description */
+    let result = { match: false, error: null, lines: new_lines };
+    new_lines.push(old_lines[ index ]);
+    return this.increment( result, index );
+  }
+
+  run( input_lines ) {
+    // let result = this.char( input );
+    let ast = {};
+    // let starting_function = {
+    //   constraints, ...
+    // }
+    let mode_functions = {
+      constraints: {
+        is_start: function () {
+          // ???? Not associated with the mode you're in, but is associated with modes
+        },
+        is_tween: function () {
+          return !input.startsWith(`|`) && !input.startsWith(/[A-z]/); // #
+        },
+        is_end: function () {
+          return input.startsWith(/[A-z]/);
+        }
+        // just the below?
+        is_mode: function ( line, current_mode ) {
+
+        }
+      },
+      constraints_table: {
+        is_start: function () {
+          if ( current_mode === `constraints` ) {
+            return input.startsWith(`|`)...
+          }
+        },
+      }
+    }
+    let current_ending_function = null;
+    let tweens = [];
+    for ( let line of input_lines ) {  // is this repeat_until?
+
+      let { location: { start, end }, mode, is_a_tween, str, ...stoof } = this.parse_one_line( line, this.char, this.something );
+      // is pre_end also tween? Leave as empty array?
+      if ( is_a_tween ) {
+        tweens.push(line);
+      } else if ( tweens.length > 0 ) {
+        if ( !is_new_mode ) {
+          current_line_list.push( ...tweens );
+        } else {
+          current_line_list = [ ...tweens, line ];
+        }
+        tweens = [];
+      } else {
+        if ( !is_new_mode ) {
+          current_line_list.push( line );
+        } else {
+          current_line_list = [ line ];
+        }
+      }
+      if ( mode === `constraints_step` ) {
+        current_ending_function = ending_functions.constraints_end;
+      }
+    }
+
+    // Maybe do other stuff
+    return result;
+  }
+
+  nested_run() {
+    /**
+     * instead of switching between contexts
+     * if enter a new "context" before the end of the previous "context", you
+     *     go one level deeper - a sub-context. Maybe a little recursive.
+     * 
+     * 
+     * */
+  }
+
+  composable_run() {
+    // ???
+  }
+
+  char( input ) {
+    if ( input.startsWith(`(`) ) {
+      return {error: null, value: input[0], original: input}
+    } else {
+      return {error: new Error(`Not a left paren`), value: null, original: input}
+    }
+  }
+
+  repeat_until( input, to_do, is_end ) {
+    let result;
+    let done = is_end( input )
+    while ( !done ) {
+      ({ result, done } = to_do(input))
+    }
+  }
+
+
+}
+
+let parser = new Parser();
+console.log(parser.run(`(thing`));
+console.log(parser.run(`frog`));
+/** Additional complications
+ * 1. Step keywords
+ * 
+ * */
+
+/** Options with original parsing to reduce complications
+ * 1. Duplicate comments at the end of Scenarios
+ * 1. Remove comments :(
+ * 1. Only allow 1 Scenario
+ * */
+
+fixts.made = {};
+fixts.made.arg =
+`@go_places
+Feature: I generate constrained random tests
+
+This doesn't do anything
+
+I make 5 random answer tests
+
+@shop
+Here?
+Scenario: I use minimal text (constrain and made)
+This is maybe a description?
+I make 5 random answer tests
+# neither does this
+  Given 1 made ALKiln constrain
+And I start the interview at "test_kickout"
+  And 1 made "end" constrain
+    | var | possible_values |
+    # blah
+    
+    | user_choice | correct;; wrong |
+  Then I reach "kickout" with:
+    | var | possible_values |
+    | stoof | ye |
+  Then I get to "blah" with this data:
+    | var | value |
+    | foo | bar |
+
+Description here too?`;
+fixts.made.expected =
+`@alkiln @generated @randomized @constraints
+Feature: I generate constrained random tests (generated by ALKiln)
+
+@generator1_scenario1_of_3
+Scenario: I use minimal text (constrain and made) (1 of 1)
+  Given I start the interview at "test_kickout"
+  And I get to any of the question ids ["end"] with this data:
+    | var | value |
+${ fixts.RANDOM_TABLE_PLACEHOLDER }
+
+@generator1_scenario2_of_3
+Scenario: I use minimal text (constrain and made) (1 of 1)
+  Given I start the interview at "test_kickout"
+  And I get to any of the question ids ["end"] with this data:
+    | var | value |
+${ fixts.RANDOM_TABLE_PLACEHOLDER }
+
+@generator1_scenario3_of_3
+Scenario: I use minimal text (constrain and made) (1 of 1)
+  Given I start the interview at "test_kickout"
+  And I get to any of the question ids ["end"] with this data:
+    | var | value |
+${ fixts.RANDOM_TABLE_PLACEHOLDER }
+`;
+
+
+
+
+
+
+
+
+
+
+const fs = require('fs');
+const fg = require(`fast-glob`);
+
+const globals = require(`../globals`);
+const session_vars = require('./session_vars');
+const get_Gherkin_AST = require(`./get_Gherkin_AST`);
+const get_error_stacks = require(`./get_error_stacks`);
+
+/**
+ * TODO: We might give various levels of categories for warnings. For example,
+ *    severe warnings (like "will skip the random test") vs. slight warnings
+ *    (like "missing number in constraints random test")
+ * TODO: Save the warnings until the tests actually run so they can show up
+ *    where other warnings show up. Does that mean making a "message to author"
+ *    internal Step of some kind?
+ * TODO: Post-MVP, don't repeat tests that the author has already created
+ * Discuss: Require author to use "Generator Scenario:" as they keyword (Also
+ *    "Generator Scenario Outline:") (or "Scenario Generator", maybe harder to
+ *    scan) for 2 reasons. 1. Gets the vocab of "generator" in early (though
+ *    that doesn't match "constraints" Step, which is a whole other language
+ *    problem we haven't solved yet.) 2. Saying "MAX_RANDOM_TESTS_PER_SCENARIO"
+ *    is confusing when "Scenario" means different things - a generator Scenario
+ *    and a regular Scenario.
+ * Discuss: Now that Log is less fragile and duplicated, shall we create a new
+ *    Log instance in here?
+ * Discuss: consider debug types that are for authors. Sort of like warnings,
+ *    but less loud.
+ * Discuss: Log.error that just returns a string formatted like an error with
+ *    the right icon, etc, without logging it to the console. We can _sort_ of
+ *    do that now, but without the icon.
+ * */
+
+
+/** Note: Keep this file non-executable so we can test it more easily. */
+
+
+module.exports = constrained_random_tests = {};
+
+let log = null;
+
+const FOLDER_NAME = globals.generated_files_folder_name;
+constrained_random_tests.create = function({
+  sources_path,
+  logger
+}) {
+  /** Given files with a certain prefix, use the text in them to generate a
+   *    feature file or files. A file generates one file with multiple
+   *    Scenarios.
+   *
+   * @param {object} obj - Named arguments
+   * @param {string} obj.sources_path - Path to the docassemble Sources folder
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {[str]} rtn.new_strings - 0 or more strings that each created a
+   *     new file.
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   *
+   * Details:
+   * - Copy sections of text from the old file
+   * - Use the Gherkin parser's AST of the constraints Step in each Scenario to
+   *   generate Story Tables
+   * - Combine various sections with the Story Tables
+   * - Make a new file with that content
+   *
+   * We're trying to find the least complex, yet sufficiently robust, system
+   *
+   * Goal:
+   * Stay as true to the author's syntax as possible so they can get useful
+   *    errors from cucumber itself.
+   *
+   * Anti-goals:
+   * - Be cucumber
+   * - Render the whole AST ourselves
+   *
+   * For examples, see tests.
+   *
+   * */
+  log = logger;
+
+  let new_files_strings = [];
+  let all_errors = [];
+
+  // Get the paths of the source files that we need to parse
+  let generator_paths = fg.sync(`${ sources_path }/${ globals.generators_prefix }*.feature`);
+  for ( let generator_path of generator_paths ) {
+
+    let file_text = fs.readFileSync( generator_path, {encoding: `utf8`});
+
+    log.info({ code: `ALK0231`, context: `generating files`, },
+      `Starting to generate the constrained random answers tests for "${ generator_path }"`
+    );
+
+    let { new_contents, errors: parse_errors } = constrained_random_tests.parse_file({
+      file_text,
+      generator_path
+    });
+    all_errors.push( ...parse_errors );
+
+    if ( new_contents ) {
+      new_files_strings.push( new_contents );
+    }
+  }
+
+  let tests_path = `${ sources_path }/${ FOLDER_NAME }`;
+  let artifacts_path = `${ session_vars.get_artifacts_path_name() }/${ FOLDER_NAME }`;
+  save_files({ tests_path, artifacts_path, file_strings: new_files_strings });
+
+  return { new_strings: new_files_strings, errors: all_errors };
+};  // Ends make_random_input_files()
+
+
+constrained_random_tests.parse_file = function({ file_text, generator_path, logger }) {
+  /** Parse and return one file's contents
+   *
+   * TODO: If there's a Gherkin parser error, log something more clear before
+   *    re-throwing it?
+   * 
+   * Note: The generator file should be valid by the time it gets here.
+   * 
+   * @param {string} file_text - Full text of a generator feature file
+   *
+   * @returns {object} rtn - Named return values
+   * @returns {null | str} rtn.new_contents - `null` or string for the new file
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   *  */
+  // Unit tests call the parser alone, so they need to create their own logger.
+  if ( logger ) {
+    log = logger;
+  }
+
+  let errors = [];
+
+  let { doc_AST, errors: generator_Gherkin_errors } = get_generator_AST({ file_text, generator_path });
+  if ( generator_Gherkin_errors.length > 0 ) {
+    return { new_contents: null, errors: generator_Gherkin_errors };
+  }
+
+  let { new_contents, errors: generating_errors } = get_new_file_contents({ doc_AST, file_text, generator_path });
+  if ( generating_errors.length > 0 ) {
+    return { new_contents: null, errors: generating_errors };
+  }
+
+  let { errors: generated_parsing_errors } = validate_syntax({ file_text: new_contents, generator_path });
+  if ( generated_parsing_errors.length > 0 ) {
+    let syntax_error = log.warn({ code: `ALK0249`, context: `generating files`, before: `\n\n`, },
+      `The .feature file ALKiln generated from "${ generator_path }" had Gherkin syntax error(s)\n`,
+      ...get_error_stacks({ errors: generated_parsing_errors })
+    );
+    return { new_contents, errors: [ new Error( syntax_error )] };
+  }
+
+  return { new_contents, errors };
+}
+
+
+function get_generator_AST({ file_text, generator_path }) {
+  /** Return any errors created when Gherkin tries to parse the generator file.
+   *     If there are any errors, throw a list of all the errors.
+   * 
+   * @param {object} obj - Named arguments
+   * @param {string} obj.file_text - Text of the Gherkin file
+   * @param {string} obj.generator_path - Path to the generator file
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {object} rtn.doc_AST - Gherkin AST of a .feature file
+   * */
+  let { AST: doc_AST, errors: generator_errors } = get_Gherkin_AST({ file_text });
+
+  if ( generator_errors.length <= 0 && doc_AST.feature ) {
+    return { doc_AST, errors: [] };
+  }
+
+  /** Error handling */
+  if ( generator_errors.length > 0 ) {
+    let syntax_error = log.warn({ code: `ALK0236`, context: `generating files`, before: `\n\n`, },
+      `The author's generator .feature file at "${ generator_path }" Gherkin syntax error(s). You might see more warnings above or below this one.\n`,
+      ...get_error_stacks({ errors: generator_errors })
+    );
+    return { doc_AST: null, errors: [ new Error( syntax_error )] };
+  }
+
+  // We have never been able to trigger `!doc_AST`
+
+  if ( !doc_AST.feature ) {
+    let feature_error = log.warn({ code: `ALK0254`, context: `generating files`, before: `\n\n`, },
+      `The author's generator .feature file at "${ generator_path }" needs to include the \`Feature\` keyword.\n`
+    );
+    return { doc_AST: null, errors: [ new Error( feature_error )] };
+  }
+
+  // Should not get here
+  let unknown_error = log.debug({ code: `ALK0255`, context: `generating files`, before: `\n\n`, },
+    `The author's generator .feature file at "${ generator_path }" ran into an unknown error when ALKiln tried to parse it.\n`
+  );
+  return { doc_AST, errors: [ new Error( unknown_error )] };
+}
+
+
+function validate_syntax({ file_text }) {
+  /** Return any errors we get from running the text through the Gherkin parser
+   * 
+   * @param {object} obj - Named arguments
+   * @param {str} obj.file_text - Text of the Gherkin file
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   *  */
+  let { errors: generated_parsing_errors } = get_Gherkin_AST({ file_text });
+  return { errors: generated_parsing_errors || [] };
+}
+
+
+function save_files({ tests_path, artifacts_path, file_strings }) {
+  /** Save each test file string to an artifacts folder and a folder that
+   *     cucumber will use to run tests.
+   * 
+   * @param { object } obj - Named arguments
+   * @param { str } tests_path - Path where cucumberjs will find these files
+   * @param { str } artifacts_path - Artifacts folder path
+   * @param { [str] } file_strings - Each string will be a test file
+   * 
+   * @returns { undefined }
+   * */
+  // Delete the old files no matter what
+  delete_previous_tests_from_sources_folders_for_ALKiln_developers({ tests_path });
+
+  if ( file_strings.length === 0 ) { return; }
+
+  // Implementation note: This has no error if the folder already exists
+  fs.mkdirSync( tests_path, { recursive: true });
+  fs.mkdirSync( artifacts_path, { recursive: true });
+
+  // TODO: For internal testing, create a separate GitHub workflow to test the
+  //    number of files that were generated
+  log.debug({ code: `ALK0250`, context: `generating files`, },
+    `Saving ${ file_strings.length } newly generated files in "${ tests_path }"`
+  );
+
+  let count = 1;
+  for ( let file_str of file_strings ) {
+    let filename = `${ count }_${ Date.now() }.feature`;
+    count++;
+    // Implementation note: If the files don't exist, this creates them
+    fs.appendFileSync( `${ tests_path }/${ filename }`, file_str );
+    fs.appendFileSync( `${ artifacts_path }/${ filename }`, file_str );
+  }
+
+  log.debug({ code: `ALK0252`, context: `generating files`, },
+    `Saved new generated files:`, fs.readdirSync( tests_path )
+  );
+
+}
+
+
+function delete_previous_tests_from_sources_folders_for_ALKiln_developers({ tests_path }) {
+  /** Delete previously generated files from this folder if they exist because
+   *    otherwise those tests will run again too (like for ALKiln devs).
+   * 
+   * Note: All the relevant tests that cucumber will run will be on the paths
+   *    that come in here, so all *relevant* old files will get deleted, even if
+   *    there are previous files hanging around somewhere else.
+   * 
+   * Research: How will this folder behave on the Playground? Do we need to
+   *    clean up at the end too?
+   * */
+  if ( !fs.existsSync( tests_path )) { return; }
+  log.debug({ code: `ALK0251`, context: `generating files`, },
+    `Deleting previously generated files:`, fs.readdirSync( tests_path )
+  );
+  fs.rmSync( tests_path, { recursive: true, force: true });
+}
+
+
+function get_new_file_contents({ doc_AST={}, file_text=``, generator_path }) {
+  /** Return the text for one new file with tests based on one generator file.
+   *
+   * Note: Right now it is out of scope to save comments in constraints Steps.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.doc_AST - Gherkin-parsed abstract syntax tree of
+   *    generator file
+   * @param {string} obj.file_text - String of the whole generator file
+   * @param {string} obj.generator_path - Path to the generator file
+   *
+   * @returns {null | string} - The text (Feature, Scenarios, etc) for the new
+   *     file
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {null | str} rtn.new_contents - `null` or string for the new file
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   * */
+
+  // `doc_AST.feature.children` seem to always be defined by here
+  let scenario_objs = doc_AST.feature.children;
+  if ( !scenario_objs[0] ) {
+    let syntax_error = log.warn({ code: `ALK0256`, context: `generating files`, before: `\n\n`, },
+      `The author's generator .feature file at "${ generator_path }" may be missing its Scenarios.\n`
+    );
+    return { new_contents: null, errors: [ new Error( syntax_error ) ]};
+  }
+  // `scenario_objs[0].scenario` seems to always be defined by here
+
+
+  let generation_errors = [];
+
+  let generator_lines = file_text.split(`\n`);
+
+  let feature_text = get_Feature_text({
+    feature: doc_AST.feature,
+    generator_lines
+  });
+
+  let { scenarios_strings, errors: scenarios_errors } = get_Scenarios({
+    scenario_objs,
+    generator_lines
+  });
+  generation_errors.push( ...scenarios_errors );
+
+
+  let count_msg = `ALKiln generated ${ scenarios_strings.length } Scenarios`;
+
+  if ( scenarios_strings.length === 0 ) {
+    let error = log.warn({ code: `ALK0246`, context: `generating files`, }, count_msg );
+    generation_errors.push( new Error( error ));
+    return { new_contents: null, errors: generation_errors };
+  }
+
+  log.info({ code: `ALK0247`, context: `generating files`, }, count_msg );
+
+  let scenarios_combined = scenarios_strings.join(`\n`);
+  let new_file_contents = [ feature_text, scenarios_combined ].join(`\n`);
+
+  if ( !new_file_contents ) {
+   let msg = `Unable to generate a constrained random answers file from "${ generator_path }". See above for warnings and errors.`;
+   let error = log.warn({ code: `ALK0248`, context: `generating files`, }, msg );
+   return { new_contents: null, errors: [ new Error( error )] }; 
+  }
+
+  return { new_contents: new_file_contents, errors: generation_errors };
+}
+
+
+function get_Feature_text({ feature, generator_lines }) {
+  /** Return text of Feature section to put at the top of the new file
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.feature - Gherkin AST `feature` object
+   * @param {[string]} obj.generator_lines - Text of the generator file as a
+   *     list
+   *
+   * @returns {string} - Text of the new file's Feature section
+   * */
+  add_Feature_randomization_indicators({ generator_lines, feature });
+
+  let first_scenario = feature.children[0].scenario;
+  let first_Scenario_line = get_Scenario_start_line_num({ scenario: first_scenario });
+  let first_Scenario_file_index = as_index( first_Scenario_line );
+  let index_of_last_line = first_Scenario_file_index - 1;
+
+  let feature_text = generator_lines.slice(
+    0, index_of_last_line + 1  // `slice` excludes the last index
+  ).join(`\n`);
+
+  return feature_text;
+}
+
+
+function get_Scenarios({ scenario_objs, generator_lines }) {
+  /** Return all the strings of the generated Scenarios and any Errors we ran
+   *    into.
+   * 
+   * @param {object} obj - Named arguments
+   * @param {object} obj.scenario_objs - Gherkin Scenario objects
+   * @param {[str]} obj.generator_lines - List of lines in the generator file
+   * 
+   * Starting here, functions' return values should now include lists of warning
+   *     messages. If a Scenario gets any warnings, we will add a "warnings"
+   *     Step to that Scenario. Implement over time.
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {[str]} rtn.scenarios - 0 or more Scenario strings
+   * @returns {[Error]} rtn.errors - 0 or more Error objects
+   * */
+  let errs_n_warns = new Misbehaviors();
+
+  let all_Scenarios_new_strings = [];
+  for ( let scenario_obj_i = 0; scenario_obj_i < scenario_objs.length; scenario_obj_i++ ) {
+
+    errs_n_warns.reset_warnings();
+
+    /** Start returning warnings here. */
+
+    // Get all randomized Scenarios from one generator Scenario
+    let generator_Scenario = scenario_objs[ scenario_obj_i ].scenario;
+
+    // Get the values for the various Steps that have to come before any other
+    //     Steps. Right now, that's only num_to_generate. Premature? Ask Will.
+    let {
+      num_to_generate,
+      warnings: first_Steps_warnings,
+      errors: first_Steps_errors
+    } = get_first_Steps({ scenario: generator_Scenario });
+    errs_n_warns.add({
+      warnings: first_Steps_warnings, errors: first_Steps_errors
+    });
+
+    // // Examples of constraints Steps
+    // // And I generate 34 tests that get to any of ["end"] when I pick from these constraints:
+    // // And I make 1 constrained random test that get to "end1", "end 2", or "end-3" with:
+    // let {
+    //   constraints_Step,
+    //   warnings: constraints_warnings,
+    //   errors: constraints_errors
+    // } = get_constraints_Step({ generator_Scenario });
+    // errs_n_warns.add({ warnings: constraints_warnings, errors: constraints_errors });
+    // if ( errs_n_warns.errors.length > 0 ) { continue; }
+
+    // // let {
+    // //   num_to_generate,
+    // //   warnings: num_warnings,
+    // //   errors: num_errors
+    // // } = get_number_of_Scenarios_to_generate({ step_text: constraints_Step.text });
+    // // errs_n_warns.add({ warnings: num_warnings, errors: num_errors });
+
+    // let {
+    //   ids: final_page_ids,
+    //   warning: ids_warnings,
+    //   errors: ids_errors
+    // } = get_final_ids({ step_text: constraints_Step.text });
+    // errs_n_warns.add({ warnings: ids_warnings, errors: ids_errors });
+    // if ( final_page_ids === null ) { continue; }
+
+    // let {
+    //   story_tables: generated_story_tables_strs,
+    //   warnings: story_tables_warnings,
+    //   errors: story_tables_errors
+    // } = get_unique_Story_Tables_strings({
+    //   num_to_generate,
+    //   ids: final_page_ids,
+    //   step: constraints_Step
+    // });
+    // errs_n_warns.add({ warnings: story_tables_warnings, errors: story_tables_errors });
+
+    // /** Stop returning warnings here. */
+
+    // let { warnings_Step, errors: warning_step_errors } = get_warnings_Step({
+    //   warnings: errs_n_warns.warnings,
+    //   step_text: constraints_Step.text
+    // });
+    // errs_n_warns.add({ errors: warning_step_errors });
+    
+    // // The Scenario top and bottom will wrap every generated Story Table for
+    // //    this generator Scenario
+    // let all_scenarios_top = get_pre_constraints({
+    //   generator_Scenario,
+    //   constraints_Step,
+    //   generator_lines,
+    //   has_warnings: errs_n_warns.warnings.length > 0
+    // });
+    // let all_scenarios_bottom = get_post_constraints({
+    //   next_Scenario: (scenario_objs[ scenario_obj_i + 1 ] || {}).scenario,
+    //   constraints_Step,
+    //   generator_lines
+    // });
+
+    // let generated_Scenarios_str = get_generated_Scenarios_str({
+    //   all_scenarios_top,
+    //   warnings_Step,
+    //   generator_id: scenario_obj_i,
+    //   story_tables: generated_story_tables_strs,
+    //   all_scenarios_bottom
+    // });
+
+    // all_Scenarios_new_strings.push( generated_Scenarios_str );
+  }  // ends for every scenario_container
+
+  // return { scenarios_strings: all_Scenarios_new_strings, errors: errs_n_warns.errors }
+  return { scenarios_strings: ['Feature: deving it'], errors: [] };
+}  // Ends get_Scenarios()
+
+
+class Misbehaviors {
+  /** Accumulates and manages errors and warnings lists. This lets you
+   *    accumulate errors for a whole function. A loop in that function, though,
+   *    can build up warnings just for that loop, after which you can reset the
+   *    warnings list for the next loop. Each loop can add up its own warnings.
+   * 
+   * Example:
+   * 
+   * function do_important_things() {
+   *   let misfits = new Misbehaviors();
+   *   
+   *   let { result, errors } = func();
+   *   misfits.add({ errors });
+   * 
+   *   for ( let item of items ) {
+   * 
+   *     misfits.reset_warnings();
+   * 
+   *     let { foo, warnings1, errors1 } = func1( item );
+   *     misfits.add({ warnings: warnings1, errors: errors1 });
+   * 
+   *     let { bar, warnings2, errors2 } = func2( item );
+   *     misfits.add({ warnings: warnings2, errors: errors2 });
+   * 
+   *     console.log( misfits.warnings );
+   *     // Loop 1: [ "oops", "darn" ]
+   *     // Loop 2: [ "shoot", "zoinks" ]
+   *   }
+   * 
+   *   console.log( misfits.errors );
+   *   // [ "ahh!", "gorramit", "that's done it" ]
+   * }
+   * */
+  constructor() {
+    this.errors = [];
+    this.warnings = [];
+  }
+
+  reset_warnings() {
+    /** Sets warnings to an empty list. This is useful inside a loop that still
+     *    needs to keep 
+     * 
+     * @returns {undefined}
+     * */
+    this.warnings = [];
+  }
+
+  add({ errors=[], warnings=[] }) {
+    /** Adds errors and/or warnings to their list
+     * 
+     * @param {obj} obj - Named arguments
+     * @param {[str]} obj.warnings - (Optional) 0 or more warning messages
+     * @param {[Error]} obj.errors - (Optional) 0 or more Error objects
+     * 
+     * @returns {undefined}
+     * */
+    if ( this.errors ) { this.errors.push( ...errors ); }
+    if (this.warnings ) { this.warnings.push( ...warnings ); }
+  }
+}
+
+
+function get_first_Steps({ scenario }) {
+  /**
+   * 
+   * Discuss: If a "first" Step appears multiple times, should that be an error
+   *     or a warning?
+   * */
+  let misfits = new Misbehaviors();
+
+  let first_vals = {
+    num_to_make: null,
+  };
+
+  // let index_of_first_non_first_Step = null;
+  let step_index = -1;
+  for ( let step of steps ) {
+
+    step_index++;
+    let all_results = [];
+
+    /** Number of tests to generate */
+    let num_results = get_number_of_Scenarios_to_generate2({
+      step,
+      prev_num_to_make: first_vals.num_to_make
+    });
+    misfits.add({ warnings: num_results.warnings, errors: num_results.errors });
+    if ( num_results.num_to_make !== null && first_vals.num_to_make !== null ) {
+      misfits.add({ warnings: log.warn({ code: `ALK0260`, context: `generating files`, },
+          `A generator Scenario has too many Steps that set the number of tests to generate. The Scenario's name:\n${ scenario.name }`
+        )
+      })
+    }
+
+    first_vals.num_to_make = num_results.num_to_make || first_vals.num_to_make;
+    all_results.push( first_vals.num_to_make );
+
+    /** Other possible first Steps */
+    // TBA
+
+    /** Possibly the end */
+    // If none of the "first Step" values were satisfied, stop here
+    if ( all_results.every(function ( item ) { return item === null; }) ) {
+      break;
+    }
+
+  }
+
+  return { num_to_make, final_index: step_index, warnings: misfits.warnings, errors: misfits.errors };
+}
+
+
+// TODO: Consider adding "pick" and "choose" as alternatives for "constrain"
+const CONSTRAIN_REGEX = /constrain/i;  // constrained/constraint/constraints
+const RAND_REGEX = /rand/i;  // random/randomness/randomized
+const GENERAT_REGEX = /generat/i;  // generate/generates/generated/generating
+const MAKE_REGEX = /mak|mad/i;  // make/makes/made/making
+const CAPTURE_NUMBERS_REGEX = /(\d+)/g;
+function get_number_of_Scenarios_to_generate2({ step }) {
+  /** Return null or a constraints Step.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.step - A valid constraints Step Gherkin object
+   *
+   * @returns {null | object} `null` or a constraints Step
+   * */
+
+  // And ALKiln's generated/new tests can definitely get to one of "" "" with:
+  // And the author promises that the generated tests can get to one of "" "" with:
+
+  // Given ALKiln should make 10 constrained random tests
+  // mak/mad/generat, \d, constrain, rand, test???
+  let user_num = null;
+  let warnings = [];
+  let errors = [];
+
+  // Use `.test()` without `g` flag. See
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test#using_test_on_a_regex_with_the_global_flag
+  let is_num_Step = CONSTRAIN_REGEX.test( step.text )
+                            && ( RAND_REGEX.test( step.text )
+                                 || GENERAT_REGEX.test( step.text )
+                                 || MAKE_REGEX.test( step.text )
+                               );
+
+  let number_matcher = step.text.match( CAPTURE_NUMBERS_REGEX );
+
+  /** No numbers */
+  if ( !is_num_Step || number_matcher === null ) {
+    warnings.push(
+      log.warn({ code: `ALK0237`, context: `generating files`, },
+        `A constrained random answers Step is missing the number of tests to generate. ALKiln will create 1 test. The Step:\n${ step.text }`
+      )
+    );
+    return { num_to_generate: null, warnings, errors };
+  }
+
+  /** Too many numbers */
+  if ( number_matcher && number_matcher.length > 1 ) {
+    // Some feedback indicated using the last number makes more sense to people
+    //    than the first
+    user_num = parseInt( number_matcher[ number_matcher.length - 1 ]);
+    warnings.push(
+      log.warn({ code: `ALK0238`, context: `generating files`, },
+        `This constrained random answers Step is ambiguous because it has more than 1 number. ALKiln will use the last number the author gave ("${ user_num }"). The Step:\n${ step.text }`,
+      )
+    );
+  }
+
+  /** Happy path */
+  if ( number_matcher && !user_num ) {
+    user_num = parseInt( number_matcher[ 0 ]);
+  }
+
+  let num_to_generate = Math.min(
+    session_vars.get_max_tests_per_generator_scenario(),
+    user_num
+  );
+
+  if ( num_to_generate !== user_num ) {
+    warnings.push(
+      log.warn({ code: `ALK0253`, context: `generating files`, },
+        `The author asked to generate ${ user_num } tests, but maximum allowed is ${ num_to_generate }. If you want to increase the maximum, use the MAX_TESTS_PER_GENERATOR_SCENARIO environment variable. Read more about environment variables at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#env-vars.`
+      )
+    );
+  }
+
+  return { num_to_generate, warnings, errors };
+}
+
+
+function add_Feature_randomization_indicators({ generator_lines=``, feature={} }) {
+  /** Mutates `generator_lines`. Modifies the tag and name of the Feature section.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.feature - Gherkin AST `feature` object
+   * @param {[string]} obj.generator_lines - Text of the generator file as a list
+   *
+   * @returns {undefined}
+   * */
+  let feature_index = as_index( feature.location.line );
+ 
+  let tag_indicator = `@alkiln @generated @randomized @constraints`;
+  let name_indicator = `(generated by ALKiln)`;
+  let new_f_name_line = ``;
+
+  if ( feature.tags.length > 0 ) {
+    // Modify existing tags
+    let tags_index = as_index( feature.tags[0].location.line );
+    let tags_starter = generator_lines[ tags_index ];
+
+    generator_lines[ tags_index ] = `${ tags_starter } ${ tag_indicator }`;
+    new_f_name_line = generator_lines[ feature_index ];
+
+  } else {
+    // If no existing tags, add new tag line
+    new_f_name_line = `${ tag_indicator }\n${ generator_lines[ feature_index ] }`;
+  }
+
+  generator_lines[ feature_index ] = `${ new_f_name_line } ${ name_indicator }`;
+}
+
+
+function get_constraints_Step({ generator_Scenario }) {
+  /** Return all the constraint Steps objects in a generator Scenario. Give
+   *    warnings if needed. There should only be 1, but we all make mistakes. If
+   *    there is an error, return the ALKiln error object.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.generator_Scenario - A valid Gherkin AST object of one Scenario
+   *
+   * @returns {object} rtn - Named return values
+   * @returns {[object]} rtn.constraints_Steps - 0 or more constraints Steps in
+   *     this Scenario.
+   * @returns {[str]} rtn.warnings - 0 or more warning messages.
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   * */
+  let constraints_Steps = [];
+  let errors = [];
+  let warnings = [];
+
+  for ( let step of generator_Scenario.steps ) {
+    let possible_constraints_Step = get_if_is_constraints_Step({ step });
+    if ( possible_constraints_Step === null ) { continue; }
+
+    constraints_Steps.push( possible_constraints_Step );
+
+    if ( !possible_constraints_Step.dataTable ) {
+
+      let msg = `The **table** of the constrained random answers Step is missing in the Scenario at line ${ generator_Scenario.location.line } - "${ generator_Scenario.name }"`;
+      let error = log.warn({ code: `ALK0239`, context: `generating files`, }, msg );
+      errors.push( new Error( error ));
+
+    } else if ( possible_constraints_Step.dataTable.rows.length === 1 ) {
+
+      let msg = `There is only a header row in the **table** of the constrained random answers Step in the Scenario at line ${ generator_Scenario.location.line } - "${ generator_Scenario.name }"`;
+      let error = log.warn({ code: `ALK0242`, context: `generating files`, }, msg );
+      errors.push( new Error( error ));
+
+    }
+
+  }  // ends for every step
+
+  let num_Steps_found = constraints_Steps.length;
+
+  if ( num_Steps_found > 1 ) {
+    let msg = `A generator Scenario can only have 1 constraints Step. The Scenario at line ${ generator_Scenario.location.line } has ${ num_Steps_found } constraints Steps. The Scenario description: "${ generator_Scenario.name }"`
+    let error = log.warn({ code: `ALK0240`, context: `generating files`, }, msg );
+    return { constraints_Step: null, errors: [ ...errors, new Error( error )] };
+  }
+
+  if ( num_Steps_found === 0 ) {
+    // TODO: link to docs for the right syntax
+    let msg = `The generator Scenario is missing a constrained random answers Step. Is there a typo in the Step? The Scenario starts at line ${ generator_Scenario.location.line } - "${ generator_Scenario.name }"`;
+    let error = log.warn({ code: `ALK0241`, context: `generating files`, }, msg );
+    return { constraints_Step: null, errors: [ ...errors, new Error( error )] };
+  }
+
+  return { constraints_Step: constraints_Steps[0], warnings, errors };
+}
+
+
+// // Tests to find the step
+// // TODO: Consider adding "pick" and "choose" as alternatives for "constrain"
+// const CONSTRAIN_REGEX = /constrain/i;  // constrained/constraint/constraints
+// const RAND_REGEX = /rand/i;
+// const GENERAT_REGEX = /generat/i;  // generate/generates/generated/generating
+// const MAKE_REGEX = /mak|mad/i;  // make/makes/made/making
+function get_if_is_constraints_Step({ step }) {
+  /** Return null or a constraints Step.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.step - A valid constraints Step Gherkin object
+   *
+   * @returns {null | object} `null` or a constraints Step
+   * */
+  // Use `.test()` without `g` flag. See
+  // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test#using_test_on_a_regex_with_the_global_flag
+  let is_constraints_step = CONSTRAIN_REGEX.test( step.text )
+                            && ( RAND_REGEX.test( step.text )
+                                 || GENERAT_REGEX.test( step.text )
+                                 || MAKE_REGEX.test( step.text )
+                            );
+  // Example: And I generate 34 tests that get to any of ["end"] when I pick from these constraints:
+  // Example: And I make 1 constrained random test that get to "end1", "end 2", or "end-3" with:
+  if ( is_constraints_step ) {
+    return step;
+  }
+
+  return null;
+}
+
+
+function get_unique_Story_Tables_strings({ num_to_generate, ids, step }) {
+  /** Return all the necessary randomized Story Tables as strings. Make sure
+   *    they are unique.
+   *
+   * @param {object} obj - Named arguments
+   * @param {int} obj.num_to_generate Number of Story tables to generate
+   * @param {[string]} obj.ids The question ids that any of the Story Tables can
+   *     reach
+   * @parm {object} obj.step A valid constraints Step Gherkin object
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {[str]} rtn.constraints_Steps - 0 or more Story Tables (see docs).
+   * @returns {[str]} rtn.warnings - 0 or more warning messages.
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   *  */
+  let story_tables = [];
+  let warnings = [];
+  let errors = [];
+
+  // Each new Story Table Step starts the same way
+  let step_indent = get_authors_indent({ located: step });
+  let table_start = `${ step_indent }And I get to any of the question ids [${ ids.join(`, `) }] with this data:`;
+
+  for ( let table_i = 0; table_i < num_to_generate; table_i++ ) {
+
+    let num_attempts = 0;
+    let max_attempts = 10;
+    let is_unique = false;
+
+    while ( !is_unique && num_attempts < max_attempts ) {
+
+      let story_table = get_random_Story_Table({
+        table_start,
+        rows: step.dataTable.rows
+      });
+
+      if ( story_tables.includes( story_table )) {
+        num_attempts += 1;
+        continue;
+      }
+
+      is_unique = true;
+      story_tables.push( story_table );
+
+    }  // ends while table is not unique
+  }  // ends for number of tests
+
+  // // Discuss: Warn of missing table?
+  // if ( story_tables.length === 0 ) {}
+
+  if ( story_tables.length < num_to_generate ) {
+    // Discuss: Debug log or warning to developer? If the latter, need to make it pretty
+    warnings.push(
+      log.warn({ code: `ALK0243`, context: `generating files`, },
+        `ALKiln only managed to make ${ story_tables.length } unique tests out of the ${ num_to_generate } asked for given the options:`,
+        get_flatter_Step({ step })
+      )
+    );
+  }
+
+  return { story_tables, warnings, errors };
+};
+
+
+function get_random_Story_Table({ table_start, rows }) {
+  /** Return a randomized Story Table string
+   *
+   * @param {object} obj - Named arguments
+   * @param {string} obj.table_start - The start of the Story Table Step
+   * @param {object} obj.rows - Gherkin AST of a `.dataTable.rows`
+   *
+   * @returns {string} - String of the whole Story Table Step
+   * */
+  let story_table_parts = [ table_start ];
+
+  for ( let row_i = 0; row_i < rows.length; row_i++ ) {
+
+    let row = rows[ row_i ];
+
+    if ( row_i === 0 ) {
+      story_table_parts.push( get_table_header({ row }) );
+      continue;
+    }
+
+    story_table_parts.push( get_random_table_row({ row }) );
+
+  }
+
+  let story_table = story_table_parts.join(`\n`);
+  return story_table;
+}
+
+
+function get_flatter_Step({ step }) {
+  /** Given a Gherkin `step` object, returns an object that is a less nested
+   *    version of the `step` object.
+   *
+   * Yes, this is annoying to test, but it's a fairly simple way to show enough
+   *    info about the Step to be useful.
+   *
+   * Discuss: Should this go in the Log class?
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.step - Valid Gherkin `step` object
+   *
+   * @returns {{ text, rows: [[str1, str2], ...] }} - Flatter version of `step`
+   * */
+  let simple = { text: step.text, rows: [] };
+  for ( let row of step.dataTable.rows ) {
+    let cells = [];
+    for ( let cell of row.cells ) {
+      cells.push( cell.value );
+    }
+    simple.rows.push( cells );
+  }
+  return simple;
+}
+
+
+function get_table_header({ row }) {
+  /** Return the string for the Story Table header row. 2 or 3 column tables are
+   *    allowed.
+   *
+   * Discuss: Warn about wrong number of columns?
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.row Valid Gherkin dataTable.row object
+   *
+   * @returns {string} A markdown table row with 2 or 3 columns
+   * */
+  let indent = get_authors_indent({ located: row });
+  let num_cols = row.cells.length;
+  let header = `${ indent }| var | value |`;
+  if ( num_cols >= 3 ) { header += ` trigger |`; }
+  return header;
+};
+
+
+function get_random_table_row({ row }) {
+  /** Return the string of one Story Table row with a randomly chosen answer.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.row - Valid Gherkin dataTable.row object
+   *
+   * @returns {string} A markdown table row with 2 or 3 columns
+   * */
+  let indent = get_authors_indent({ located: row });
+  let cells = row.cells;
+  let num_cols = cells.length;
+
+  let answer = pick_random_answer({ answers_str: cells[1].value });
+
+  let row_str = `${ indent }| ${ cells[0].value } | ${ answer } |`;
+  if ( cells.length >= 3 ) { row_str += ` ${ cells[2].value } |`; }
+  return row_str;
+};
+
+
+// Make a placeholder where we will make the scenario unique
+let ID_PLACEHOLDER = `ALKILN_SCENARIO_RANDOM_ID_PLACEHOLDER`;
+function get_generated_Scenarios_str({
+  all_scenarios_top,
+  warnings_Step = null,
+  generator_id,
+  story_tables,
+  all_scenarios_bottom
+}) {
+  /** Return the string for the combined Scenarios.
+   *
+   * @param {object} obj - Named arguments
+   * @param {string} obj.all_scenarios_top - Scenario text that comes before the
+   *     constraints Step
+   * @param {string} obj.warnings_Step - Optional. Default is `null`. Step to
+   *     show the author a warning message.
+   * @param {int | string} obj.generator_id - ID of the generating Scenario
+   * @param {[string]} obj.story_tables - Story Table text for every Scenario
+   *     that we need to generate
+   * @param {string} obj.all_scenarios_bottom - Scenario text that comes after the
+   *     constraints Step
+   *
+   * @returns {[string]} - List of complete Scenario strings
+   * */
+  let scenarios = [];
+  for ( let table_i = 0; table_i < story_tables.length; table_i++ ) {
+
+    let generator_num = generator_id + 1;
+    let scenario_num = table_i + 1;
+    let total_scenarios = story_tables.length;
+    let scenario_tag = `generator${ generator_num }_scenario${ scenario_num }_of_${ total_scenarios }`;
+    let with_tag = all_scenarios_top.replaceAll( ID_PLACEHOLDER, scenario_tag );
+    let random_top = with_tag.replaceAll( SCENARIO_COUNT_PLACEHOLDER, `${ scenario_num } of ${ total_scenarios }` );
+
+    let story_table = story_tables[ table_i ];
+
+    let scenario_items = [ random_top ];
+    if ( warnings_Step ) { scenario_items.push( warnings_Step ); }
+    scenario_items.push( story_table, all_scenarios_bottom );
+
+    let scenario_str = scenario_items.join(`\n`);
+    scenarios.push( scenario_str );
+  }
+
+  let this_Scenarios_strings = scenarios.join(`\n`);
+  return this_Scenarios_strings;
+};
+
+
+let SCENARIO_COUNT_PLACEHOLDER = `ALKILN_GENEREATED_SCENARIO_COUNT_PLACEHOLDER`;
+function get_pre_constraints({
+  generator_Scenario,
+  constraints_Step,
+  generator_lines,
+  has_warnings
+}) {
+  /** Return the Scenario text that comes before the first constraints Step.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.generator_Scenario - AST of the Scenario
+   * @param {object} obj.constraints_Step - AST of the constraints Step
+   *     Step
+   * @param {[string]} obj.generator_lines - List of lines from the generator
+   *     file
+   * @param {boolean} obj.has_warnings - `true` if generating the Scenario
+   *     created warnings
+   *
+   * @returns {string} - Scenario text that comes before the first constraints
+   *     Step
+   * */
+  // Use a shorter name as there are a lot of long lines of code
+  let lines = generator_lines;
+  set_tags_and_description({ scenario: generator_Scenario, lines, has_warnings });
+  let start_line_num = get_Scenario_start_line_num({ scenario: generator_Scenario });
+  let top_start_index = as_index( start_line_num );
+
+  let top_end_index = get_index_before({ line_num: constraints_Step.location.line });
+
+  // Turn the list of lines for the pre-constraints section of the Scenario into
+  //    a text block
+  let scenario_top_text = lines.slice(
+    top_start_index,
+    top_end_index + 1  // `slice` excludes the terminal number
+  ).join(`\n`);
+
+  return scenario_top_text;
+};
+
+
+function set_tags_and_description({ scenario, lines, has_warnings }) {
+  /** Mutate the file lines to add placeholders for scenario text that will
+   *    show it is a generated test and give it unique identifiers.
+   * 
+   * 
+   * @param {object} obj - Named arguments
+   * @param {object} obj.scenario - AST of a Gherkin scenario
+   * @param {object} obj.lines - File text lines to mutate with the new text
+   * @param {object} obj.has_warnings - `true` if the Scenario creation caused
+   *     warning messages
+   * 
+   * @returns {undefined}
+   * */
+
+  /**
+   * Add ALKiln tags by mutating the tag line if it exists. If not, mutate the
+   *     keyword/description line by adding ALKiln's tags above the existing
+   *     text.
+   * */
+  let pre_description = ``;
+
+  let alkiln_tags = [ `@${ ID_PLACEHOLDER }` ];
+  if ( has_warnings ) { alkiln_tags.push(`@alkiln_warning`); }
+
+  if ( scenario.tags.length > 0 ) {
+    // Mutate the tags line to add new tags
+    let tags_index = as_index( scenario.tags[0].location.line );
+    let new_tags = [ lines[ tags_index ], ...alkiln_tags ];
+    lines[ tags_index ] = new_tags.join(` `);
+
+  } else {
+    // Add an artificial new line with alkiln's tags
+    pre_description = `${ alkiln_tags.join(" ")}\n`;
+  }
+
+  let description_index = as_index( scenario.location.line );
+  let new_description = `${ lines[ description_index ] } (${ SCENARIO_COUNT_PLACEHOLDER })`;
+  // Potentially mutate the new_description line
+  lines[ description_index ] = `${ pre_description }${ new_description }`;
+};
+
+
+function get_post_constraints({ next_Scenario, constraints_Step, generator_lines }) {
+  /** Return the Scenario text that comes after the last constraints Step.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object | undefined} obj.next_Scenario - AST of the Scenario after this Scenario
+   * @param {object} obj.constraints_Step - AST of the constraints Step
+   * @param {[string]} obj.generator_lines - List of lines from the generator file
+   *
+   * @returns {string} - Scenario text that comes after the last constraints
+   *     Step
+   * */
+  let rows = constraints_Step.dataTable.rows;
+  let constraints_end_index = as_index( rows[ rows.length - 1].location.line );
+  let bottom_start_index = constraints_end_index + 1;
+
+  if ( !next_Scenario ) {
+    // Get lines till the end of the file
+    let scenario_bottom_text = generator_lines.slice(
+      bottom_start_index
+    ).join(`\n`);
+    return scenario_bottom_text;
+  }
+
+  // Get lines till the start of the next Scenario
+  let next_Scenario_start_line = get_Scenario_start_line_num({ scenario: next_Scenario });
+  let bottom_end_index = get_index_before({ line_num: next_Scenario_start_line });
+
+  let scenario_bottom_text = generator_lines.slice(
+    bottom_start_index,
+    bottom_end_index + 1  // `slice` excludes the terminal number
+  ).join(`\n`);
+
+  return scenario_bottom_text;
+};
+
+
+function get_index_before({ line_num }) {
+  /** Return the index in the file line list that corresponds to the given
+   *    Gherkin 1-indexed line number. This is mostly here as a name that
+   *    clarifies what the code is doing and hides a little bit of the
+   *    complexity.
+   *
+   * Discuss: is get_index_before() worth abstracting?
+   *
+   * Each object in the Gherkin AST will have a `location` object that includes
+   *    the item's line number (`{line: 1}`). Each line number represents a line
+   *    in the file and therefore an item in the `generator_lines` list. The line
+   *    numbers are 1-indexed. That means the location of `{line: 1}` in the AST
+   *    refers to `generator_lines[0]`.
+   *
+   * @param {object} obj - Named arguments
+   * @param {int} obj.line_num - Integer of a Gherkin 1-indexed line number
+   *
+   * @returns {int} - File-line-list index that corresponds to the Gherkin line
+   *     number
+   * */
+  let line_as_index = as_index( line_num );
+  return line_as_index - 1;
+};
+
+
+// function get_index_after({ line_num }) {};
+
+
+function get_authors_indent({ located }) {
+  /** Return a whitespace string representing the indentation for a given
+   *    Gherkin location object.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.located - Gherkin AST object with a location property
+   *
+   * @returns {string} - A whitespace string representing the indentation for a
+   *    given Gherkin location object.
+   * */
+  if ( typeof located !== 'object' || !located.location ) {
+    return ``;
+  }
+  return ` `.repeat( located.location.column - 1 );
+};
+
+
+// const CAPTURE_NUMBERS_REGEX = /(\d+)/g;
+function get_number_of_Scenarios_to_generate({ step_text }) {
+  /** Return the number of random constraints tests to generate with a minimum
+   *    of 1 test.
+   * 
+   * Gives warnings instead of errors, defaulting to returning `1`.
+   *
+   * @param {object} obj - Named arguments
+   * @param {string} obj.step_text - The text of a constraints Step
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {int} rtn.num_to_generate - Number of tests to generate. Min is 1.
+   * @returns {[str]} rtn.warnings - 0 or more warning messages.
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   * */
+  let user_num = null;
+  let warnings = [];
+  let errors = [];
+  let number_matcher = step_text.match( CAPTURE_NUMBERS_REGEX );
+
+  /** No numbers */
+  if ( number_matcher === null ) {
+    warnings.push(
+      log.warn({ code: `ALK0237`, context: `generating files`, },
+        `A constrained random answers Step is missing the number of tests to generate. ALKiln will create 1 test. The Step:\n${ step_text }`
+      )
+    );
+    user_num = 1;
+  }
+
+  /** Too many numbers */
+  if ( number_matcher && number_matcher.length > 1 ) {
+    // Some feedback indicated using the last number makes more sense to people
+    //    than the first
+    user_num = parseInt( number_matcher[ number_matcher.length - 1 ]);
+    warnings.push(
+      log.warn({ code: `ALK0238`, context: `generating files`, },
+        `This constrained random answers Step is ambiguous because it has more than 1 number. ALKiln will use the last number the author gave ("${ user_num }"). The Step:\n${ step_text }`,
+      )
+    );
+    
+  }
+
+  /** Happy path */
+  if ( number_matcher && !user_num ) {
+    user_num = parseInt( number_matcher[ 0 ]);
+  }
+
+  let num_to_generate = Math.min(
+    session_vars.get_max_tests_per_generator_scenario(),
+    user_num
+  );
+
+  if ( num_to_generate !== user_num ) {
+    warnings.push(
+      log.warn({ code: `ALK0253`, context: `generating files`, },
+        `The author asked to generate ${ user_num } tests, but maximum allowed is ${ num_to_generate }. If you want to increase the maximum, use the MAX_TESTS_PER_GENERATOR_SCENARIO environment variable. Read more about environment variables at https://assemblyline.suffolklitlab.org/docs/alkiln/writing/#env-vars.`
+      )
+    );
+  }
+
+  return { num_to_generate, warnings, errors };
+}
+
+
+function get_warnings_Step({ warnings = [], step_text }) {
+  /** Returns the text for any warnings that need to be added to the Scenario
+   * 
+   * @param {object} obj - Named arguments
+   * @param {[string]} obj.warnings - 0 or more warning messages
+   * @param {string} obj.step_text - Constraints Step text (to match indent)
+   * 
+   * @returns {object} rtn - Named return values
+   * @returns {str} rtn.warnings_Step - cucumberjs Step to show author a warning
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   * */
+  let errors = [];
+
+  if ( warnings.length === 0 ) { return { warnings_Step: null, errors }; }
+
+  let indent_match = step_text.match(/$\s*/);
+  let indent = ( indent_match && indent_match[ 0 ]) || `  `;
+
+  let new_warnings_lines = [];
+  new_warnings_lines.push(`${ indent }Then ALKiln warns the author about a generator problem with:`);
+  new_warnings_lines.push(`${ indent }  """`, `${ indent }  ----- Generator file warning -----`);
+
+  for ( let warning of warnings ) {
+    let warning_lines = warning.split(`\n`);
+    for ( let warning_line of warning_lines ) {
+      new_warnings_lines.push(`${ indent }  ${ warning_line }`);
+    }
+  }
+
+  new_warnings_lines.push(`${ indent }  -----`, `${ indent }  """`);
+
+  let warnings_Step = new_warnings_lines.join(`\n`);
+
+  return { warnings_Step, errors };
+}
+
+
+let CAPTURE_QUESTION_IDS_REGEX = /("[^"]+")/g;
+function get_final_ids({ step_text }) {
+  /** Return a list of docassemble question block ids (in double quotes) that
+   *    are in an ALKiln constraints Step. Every generated Story Table Step must
+   *    reach one of these ids.
+   *
+   * @param {object} obj - Named arguments
+   * @param {string} obj.step_text - The text of a constraints Step
+   *
+   * Example:
+   * get_final_ids({ step_text: `And I make 1 constrained random test that gets to "end1" or "end 2" with:` });
+   * // [`"end1"`, `"end2"`]
+   *
+   * @returns {object} rtn - Named return values
+   * @returns {["str"]} rtn.ids - 0 or more double-quoted docassemble question
+   *     block ids. Each generated Story Table Step must end at one of these
+   *     ids. this Scenario.
+   * @returns {[str]} rtn.warnings - 0 or more warning messages.
+   * @returns {[Error]} rtn.errors - 0 or more Errors.
+   * */
+  let errors = [];
+  let warnings = [];
+  
+  let ids = step_text.match( CAPTURE_QUESTION_IDS_REGEX );
+
+  if ( ids === null ) {
+    let missing_ids_msg = `The constrained random answers Step is missing its question ids. ALKiln is unable to create random tests for this generator Scenario. The Step:\n${ step_text }`;
+    let error = log.warn({ code: `ALK0245`, context: `generating files`, },
+      missing_ids_msg
+    );
+    errors.push( new Error( error ));
+  }
+
+  return { ids, warnings, errors };
+}
+
+
+function pick_random_answer({ answers_str=`` }) {
+  /** Return one of the answers from the given string of possible answers.
+   *
+   * @param {object} obj - Named arguments
+   * @param {str} obj.answers_str - A string representing one or more possible
+   *    answers. The possible answers are separated by this character
+   *    combination: `;;`
+   *
+   * Example:
+   * pick_random_answer({ answers_str: `yes;; no;; maybe` });
+   * // `no`
+   * 
+   * TODO: Add a warning in the docs that Gherkin ignores whitespace at the
+   *    start and end of columns in a table. Discuss letting authors wrap
+   *    content in backticks or some other delimiter.
+   *
+   * @returns {string} - One of the possible answers
+   * */
+  let choices = answers_str.replace(`;; `, `;;`).split(`;;`);
+  if ( choices.includes(``) ) {
+    log.debug({ code: `ALK0244`, context: `generating files`, level: `warn` },
+      `**Quiet warning** - One of the constrained random answer choices in a row in this table is "". It could be on purpose or it could be a misplaced separator (";;"). The choices: "${ answers_str }"`
+    );
+  }
+  let choice_index = Math.floor( Math.random() * choices.length );
+  return choices[ choice_index ];
+}
+
+
+function get_row_as_string({ row }) {
+  /** Return the given Gherkin row as a single markdown table row */
+  let cells = row.cells;
+  let values = cells.map(( cell ) => { return cell.value; });
+  let row_str = `| ${ values.join( ` | ` ) } |`;
+  return row_str;
+}
+
+
+function get_Scenario_start_line_num({ scenario }) {
+  /** Returns the Gherkin line number where the Scenario really starts. That
+   *    could be where the tags are or where the Scenario keyword is.
+   *
+   * @param {object} obj - Named arguments
+   * @param {object} obj.scenario - The Gherkin AST for a Scenario
+   *
+   * @returns {int} - Gherkin line number where the Scenario starts
+   * */
+  if ( scenario.tags.length > 0 ) {
+    return scenario.tags[0].location.line;
+  } else {
+    return scenario.location.line;
+  }
+}
+
+
+function as_index( line_num ) {
+  /** Given a Gherkin line number, return the file-lines-list index for that
+   *    line number. This is here mostly as a name that helps clarify what the
+   *    code is doing.
+   *
+   * Each Gherkin line number matches a line in the file and therefore an item
+   *    in the `generator_lines` list. The Gherkin line numbers are 1-indexed. That
+   *    means the location of `{line: 1}` in the AST refers to `generator_lines[0]`.
+   *
+   * @param {int} line_num - A 1-indexed Gherkin line number
+   *
+   * @returns {int} - The corresponding index in the list of lines in the
+   *    generator file
+   * */
+  return line_num - 1;
+}