Rewrite: Stepper

package.json

@@ -124,5 +124,5 @@
       ]
     ]
   },
-  "packageManager": "yarn@4.6.0"
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

src/runner/sourceRunner.ts

@@ -16,13 +16,6 @@ import { defaultAnalysisOptions } from '../modules/preprocessor/analyzer'
 import { defaultLinkerOptions } from '../modules/preprocessor/linker'
 import { parse } from '../parser/parser'
 import { AsyncScheduler, PreemptiveScheduler } from '../schedulers'
-import {
-  callee,
-  getEvaluationSteps,
-  getRedex,
-  type IStepperPropContents,
-  redexify
-} from '../stepper/stepper'
 import { sandboxedEval } from '../transpiler/evalContainer'
 import { transpile } from '../transpiler/transpiler'
 import { Chapter, type Context, type RecursivePartial, type Scheduler, Variant } from '../types'
@@ -31,6 +24,7 @@ import { compileForConcurrent } from '../vm/svml-compiler'
 import { runWithProgram } from '../vm/svml-machine'
 import type { FileGetter } from '../modules/moduleTypes'
 import { mapResult } from '../alt-langs/mapper'
+import { getSteps } from '../tracer/steppers'
 import { toSourceError } from './errors'
 import { fullJSRunner } from './fullJSRunner'
 import { determineExecutionMethod, determineVariant, resolvedErrorPromise } from './utils'
@@ -88,25 +82,11 @@ function runSubstitution(
   context: Context,
   options: IOptions
 ): Promise<Result> {
-  const steps = getEvaluationSteps(program, context, options)
-  if (context.errors.length > 0) {
-    return resolvedErrorPromise
-  }
-  const redexedSteps: IStepperPropContents[] = []
-  for (const step of steps) {
-    const redex = getRedex(step[0], step[1])
-    const redexed = redexify(step[0], step[1])
-    redexedSteps.push({
-      code: redexed[0],
-      redex: redexed[1],
-      explanation: step[2],
-      function: callee(redex, context)
-    })
-  }
+  const steps = getSteps(program, options)
   return Promise.resolve({
     status: 'finished',
     context,
-    value: redexedSteps
+    value: steps
   })
 }
 

src/tracer/README.md

@@ -0,0 +1,96 @@
+# Stepper Documentation (Draft)
+- [Stepper Documentation (Draft)](#stepper-documentation-draft)
+  - [Key changes](#key-changes)
+  - [Quickstart](#quickstart)
+  - [Implementation Details](#implementation-details)
+    - [Entry point](#entry-point)
+    - [Reduction](#reduction)
+  - [Stepper ASTs (To be updated)](#stepper-asts-to-be-updated)
+    - [`UndefinedNode`](#undefinednode)
+    - [`StepperProgram`](#stepperprogram)
+      - [Reduction](#reduction-1)
+    - [`VariableDeclaration`](#variabledeclaration)
+      - [Reduction](#reduction-2)
+
+## Key changes
+- Rewritten the code to be more cohesive and readable.
+- Better visualisation of recursion using lambda calculus concepts such as µ-terms. 
+
+## Quickstart
+First of all, make sure that you have already installed `js-slang` using `yarn`. There are many possible ways that you can work and test the code. One of my personal solution is using `yarn test`. During the development, you can edit the file from `../__test__/tracer_debug.ts` and run it with the following command:
+```bash
+yarn test -- tracer_debug.ts  > testOutput.log
+```
+Note that the flag `--silence=false` is set in order to see the output from `console.log`. In order to fully test the stepper, you can execute the following command.
+```bash
+yarn test -- tracer_full.ts` 
+```
+## Implementation Details
+Starting to work from raw estree is quite tricky, as it prevents us from using OOP principles directly. Therefore, we decided to create classes based on the original estree while implementing the `StepperBaseNode` interface. Note that this interface is subjected to change when adding more features to the stepper.
+```typescript
+// interface.ts
+export interface StepperBaseNode {
+  type: string
+  isContractible(): boolean
+  isOneStepPossible(): boolean
+  contract(): StepperBaseNode
+  oneStep(): StepperBaseNode
+  substitute(id: StepperPattern, value: StepperExpression): StepperBaseNode
+}
+```
+### Entry point
+The starting point of our stepper is at `steppers.ts` with the function `getSteps`. This function is responsible for triggering reduction until it cannot be proceed. The result from our evaluation is then stored in array `steps`. Here is the shorten version of `getSteps`.
+
+```typescript
+export function getSteps(node: StepperBaseNode) {
+  const steps = []
+  function evaluate(node) {
+    const isOneStepPossible = node.isOneStepPossible()
+    if (isOneStepPossible) {
+      const oldNode = node
+      const newNode = node.oneStep() // entry point
+      {... read global state redex and add them to steps array}
+      return evaluate(newNode) 
+    } else {
+      return node
+    }
+  }
+  evaluate(node)
+  return steps
+}
+
+```
+
+In order to keep track of the node that is reduced (i.e., the node highlighted in orange and green in the current SICP stepper), we use the global state redex to track all nodes that should be highlighted. This state is then updated dynamically during the contraction process.
+
+```typescript
+export let redex: { preRedex: StepperBaseNode[]; postRedex: StepperBaseNode[] } = {
+  preRedex: [],
+  postRedex: []
+}
+// How to use global state
+redex.preRedex = [node]
+const ret = someSortOfReduction(node)
+redex.postRedex = [ret]
+```
+### Reduction
+The main entry point of our stepper is `oneStep()`. It is where our stepper start crawling down the tree and find the node that is ready to be `contract()`. Here is a quick example.
+```typescript
+1 + 2 * 3 // (+ 1 (* 2 3))
+```
+The binary expression `(+ 1 (* 2 3))` should not be contracted since its inner node `(* 2 3)` can be contracted to `6`, before contracting the outer expression. The methods `isContractible` and `isOneStepPossible` help maneuver the logic of where to contract.
+## Stepper ASTs (To be updated)
+### `UndefinedNode`
+- Global node, literal, representing undefined
+
+### `StepperProgram`
+#### Reduction
+- If `node.body.length === 0`, the program is reduced to `StepperUndefined`.
+- If the first two statements are `oneStepPossible()`, reduce the first two statements first.
+- If the first two statements are value-inducing (e.g., `1; 2;`), remove the first statement using `contractEmpty()`.
+
+### `VariableDeclaration`
+#### Reduction
+- Reduce the `init` field first. `const x = 1 + 1;`: `1+1` is an init field.
+- If the `init` field is reduced, toggle substitution and reduce the statement to `StepperUndefined`.
+- VariableDeclaration is always contractable. PreRedex is the variable declaration statement. PostRedexes are all variables substituted.