Documentation, use interfaces and rewrite bin scripts

Author: SleeplessByte

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules\\typescript\\lib"
+}

bin/analyze.bat

@@ -1,4 +1,4 @@
 @REM Usage:
-@REM ./bin/analyze.bat two_fer ~/test/
+@REM ./bin/analyze.bat two-fer ~/test/
 
 node -r esm ./dist/analyze.js %*

bin/analyze.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env sh
 
 # Usage:
-# ./bin/analyze.sh two_fer ~/test/
+# ./bin/analyze.sh two-fer ~/folder/to/solution
 
 node -r esm ./dist/analyze.js "$@"

bin/batch-runner

@@ -0,0 +1,4 @@
+@REM Usage:
+@REM ./bin/batch.bat two-fer
+
+node -r esm ./dist/batch.js %*

bin/batch.bat

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+
+# Usage:
+# ./bin/batch.sh two-fer
+
+node -r esm ./dist/batch.js "$@"

bin/batch.sh

@@ -0,0 +1,4 @@
+@REM Usage:
+@REM ./bin/stats.bat two-fer
+
+node -r esm ./dist/stats.js %*

bin/statistics

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+
+# Usage:
+# ./bin/stats.sh two-fer
+
+node -r esm ./dist/stats.js "$@"

bin/stats.bat

@@ -1,4 +1,4 @@
-export class Exercise {
+export class ExerciseImpl implements Exercise {
   constructor(public readonly slug: string) {
     if (!slug) {
       throw new Error(`Expected valid exercise slug, got '${slug}'`)

bin/stats.sh

@@ -1,15 +1,36 @@
 import { Bootstrap } from './utils/bootstrap'
 import { find } from './analyzers/Autoload'
-import { run } from './runner'
+import { run } from './utils/runner'
 
+// The bootstrap call uses the arguments passed to the process to figure out
+// which exercise to target, where the input lives (directory input) and what
+// execution options to set.
+//
+// analyze -dc two-fer ~/test/
+//
+// For example, if arguments are passed directly, the above will run the two-fer
+// exercise analyzer with the ~/test/ input directory and turning on debug and
+// console logging.
+//
 const { exercise, options, input, logger } = Bootstrap.call()
 
 logger.log('=> DEBUG mode is on')
 logger.log(`=> exercise: ${exercise.slug}`)
 
+// The autoloader knows where an analyzer should live and tries to require it
+// so it can be instantiated here. This allows us to add new analyzers without
+// needing to update a bookkeeping construct
+//
 const AnalyzerClass = find(exercise)
 const analyzer = new AnalyzerClass()
 
+// The runner uses the execution options to determine what should happen with
+// the output. For example the --dry flag will make sure there is nothing
+// written to a file.
+//
+// The basis for the runner is calling analyzer.run(input) -- the output is then
+// logged and/or written to a file.
+//
 run(analyzer, input, options)
   .then(() => process.exit(0))
   .catch((err: any) => logger.fatal(err.toString()))

src/exercise.ts renamed to src/ExerciseImpl.ts

@@ -1,6 +1,5 @@
 import { getProcessLogger as getLogger, Logger } from '../utils/logger'
 
-import { Comment } from '../comments/comment'
 import { AnalyzerOutput } from '../output/AnalyzerOutput';
 import { ParsedSource, AstParser } from '../parsers/AstParser';
 
@@ -35,6 +34,15 @@ export abstract class AnalyzerImpl implements Analyzer {
    */
   public async run(input: Input): Promise<Output> {
     // Ensure each run has a fresh output
+    //
+    // Note: still need to wait for a run to complete before the next one can be
+    //       started. We could work around this by providing an execution
+    //       context that is fresh on each run.
+    //
+    // The reason output is not passed to execute, is that it doesn't _actually_
+    // enforce the implementing analyzer to not use local state, so we don't
+    // gain anything by it.
+    //
     this.output = new AnalyzerOutput()
 
     await this.execute(input)

src/analyze.ts

@@ -1,5 +1,3 @@
-import { Exercise } from '../exercise'
-
 import path from 'path'
 
 import { getProcessLogger } from '../utils/logger'

src/analyzers/AnalyzerImpl.ts

@@ -1,5 +1,4 @@
 import {
-  BinaryExpression,
   ConditionalExpression,
   IfStatement,
   LogicalExpression,
@@ -246,7 +245,7 @@ export class TwoFerAnalyzer extends AnalyzerImpl {
   }
 
   private checkForSolutionWithoutStringTemplate() {
-    const [expression] = extractAll<BinaryExpression>(this.mainMethod!, AST_NODE_TYPES.BinaryExpression)
+    const [expression] = extractAll(this.mainMethod!, AST_NODE_TYPES.BinaryExpression)
 
 
     //