merv-tutor

Run a small JavaScript or TypeScript file with MervLogger tracing. Logger lines go to the local MERV report (Merv-Logs + testcase logs). Your console.log still prints on the terminal and is also mirrored into the report.

Usage

npm install merv-client merv-tutor

npx merv-tutor test.js
npx merv-tutor lesson1.js lesson2.js
npx merv-tutor open

What is traced

| Concept | What you see in Merv-Logs | |--------|---------------------------| | Variables / assignments | a = 10 | | Loops (for / while / for-of / …) | ⟶ for loop body, loop vars each iteration | | if / else | ⟶ if branch / ⟶ else branch | | Functions | function foo defined, ⟶ enter function foo | | Classes / methods | class Foo defined, ⟶ enter constructor / method … | | Calls / new | call foo(1) → … | | await / Promises | await … → … | | console.log / info / warn / error | printed + console.log: … in the report | | try / catch / finally | ⟶ catch, error binding |

Example

function add(x, y) {
  return x + y;
}

class Counter {
  constructor(start) {
    this.n = start;
  }
  bump() {
    this.n += 1;
    return this.n;
  }
}

let a = 10;
let b = 20;
let c = add(a, b);

const counter = new Counter(0);
for (let i = 0; i < 3; i++) {
  counter.bump();
}

async function load() {
  return await Promise.resolve(42);
}

load().then((v) => console.log('loaded', v));

Terminal shows your console.log output. The report also has <----- File test.js ----->, the source, and step-by-step traces.

How it works

1. Reads your file (TypeScript via esbuild).
2. Writes merv-test.js with tutor hooks.
3. Runs node merv-test.js (MervLogger itself is silent on stdout; console.* is not).
4. Deletes merv-test.js unless you pass --keep.

Reports are always written under <project-root>/merv-reports, where the project root is the nearest parent folder containing package.json. Merv-Tutor does not create or require merv.properties, so running from a nested folder such as javascript/ does not create reports or configuration there.

Instrumentation uses Babel (@babel/core) for scope-aware transforms (variables, control flow, console.*, calls, await). TypeScript is still compiled with esbuild before instrumentation.

Merv-Tutor debugger (step through code)

After a run:

npx merv-tutor open

That serves the report folder and opens /merv-tutor.html in your browser (same server as merv show-report, default http://127.0.0.1:6174/merv-tutor.html).

You can run this command from any project subfolder; it opens the root-level merv-reports. Pass an explicit path only when you intentionally want to open a different report directory: npx merv-tutor open ./merv-reports.

• Summary bar: total steps, loop iterations, and how many files ran
• Files panel (when you pass more than one file): expandable/collapsible folder tree; pick a file to view; stepping auto-follows the active file
• Left: your source, line by line (current step highlighted)
• Right: table of variables in memory at that step
• Bottom right: console output (60%) beside an analysis panel (40%)
• Controls: First / Prev / Next / Last (keyboard arrows and Home/End too)

The analysis panel reports, for the file you are viewing: steps, loop iterations, time complexity, space complexity, and max loop nesting. Complexity is estimated statically from the source — time from how deeply loops nest (O(1), O(n), O(n²), …), space from whether a collection grows inside a loop. It is a teaching aid, not a proof: loops reached through helper functions are counted where they are written, and input-dependent bounds are not detected.

Pass multiple files to run them in order in one session:

npx merv-tutor part1.js part2.js

You can also run files separately. Merv-Tutor keeps a project list containing only paths that were executed through the CLI:

npx merv-tutor src/lessons/test1.js
npx merv-tutor src/examples/test2.js
npx merv-tutor open

Both paths remain under Project Files. Folder names are preserved. Clicking a file shows only that file's source, variables, console output, and analysis. Re-running the same path replaces its previous trace without duplicating the file; it does not remove other executed files.

Project trace data is stored in merv-reports/merv-tutor/latest.json (tutor runs only — not mixed with Playwright/Cucumber logs).

Variables table: shadowed names appear as separate rows (Babel binding keys: a for global, a@19 where let a is on line 19). When a block-scoped variable goes out of scope, it is removed from the table on later steps. Columns: Name, Scope, Value, Type.

Other files: only files passed to merv-tutor appear in Project Files. Files loaded only via require() / import still run normally but are not instrumented or listed unless you pass them to the CLI.

Requirements

• Node 18+
• merv-client 4.0.20+
• merv-tutor 4.0.20+