# Glossary

Use these words, and only these, for these things. Code, comments, docs, and commit messages all follow this list.

## The product

**typestrip**
: The package, `@nibling/typestrip`. It has no other name.

**mode**
: How typestrip treats TypeScript-only syntax. There are two: `erase` (the default) and `downlevel`. Call them "erase mode" and "downlevel mode". The ABI passes the mode as a number: 0 is erase, 1 is downlevel.

**erase mode**
: Removes erasable syntax only and reports everything else. Every offset is preserved. See [modes.md](modes.md).

**downlevel mode**
: Also down-levels non-erasable syntax. Lines are preserved, and columns are preserved outside converted constructs. See [modes.md](modes.md).

**erase**
: To remove a piece of TypeScript syntax by replacing its characters with spaces. Line terminators stay. A few erased characters become `;`, `(` or `)` to keep ASI and arrow-function semantics.

**down-level**
: To rewrite a non-erasable construct as the JavaScript `ts.transpileModule` would emit for it. Only downlevel mode does this.

**non-erasable syntax**
: TypeScript syntax that has runtime behavior, so it can't be erased: `enum` and `const enum`, instantiated `namespace`, parameter properties, `import x = require()`, `export =`, and legacy `<T>x` casts.

**unsupported syntax**
: Syntax that the current mode can't handle. typestrip reports it through `onError`, or throws an `UnsupportedSyntaxError` when there is no `onError`.

## The code

**engine**
: The WebAssembly module compiled from `engine/*.zena`. It has two shipped builds:
  - the **erase engine**, `build/erase.wasm`
  - the **downlevel engine**, `build/downlevel.wasm`

  The **debug engine**, `build/downlevel-debug.wasm`, is the downlevel engine plus a `dbg()` probe for the tools in `scripts/debug/`.

**wrapper**
: The JavaScript in `src/`. `core.js` holds the platform-neutral logic, and each entry adds its host hooks.

**Node entry** and **browser entry**
: `src/index.js` (the `node` export condition) and `src/browser.js` (the `default` export condition, used by browsers, workers, Deno, and workerd).

**ABI**
: The export contract between the wrapper and the engine: `init`, `inbuf`, `push`, `outbuf`, `errorCount`, `errorsPtr`, and `memory`. See [architecture.md](architecture.md#abi).

**hooks**
: The functions in `engine/hooks-downlevel.zena` that `engine/strip.zena` calls at each non-erasable construct. The erase build compiles `engine/hooks-erase.zena` instead, where every hook is a no-op stub, so the downlevel code never reaches `build/erase.wasm`.

**Zena**
: The language the engine is written in. `zena-cli` is its compiler.

## Testing

**oracle**
: The reference implementation a mode is judged against. For erase mode it is ts-blank-space. For downlevel mode it is `ts.transpileModule`.

**judge**
: The script that compares typestrip with an oracle. `test/erase.mjs` judges erase mode, and `test/downlevel.mjs` judges downlevel mode.

**corpus**
: The test inputs. Small, checked-in cases live in `corpus/`. Large inputs are fetched into `vendor/` by `scripts/vendor.sh` and `scripts/oss.sh`.

**OSS corpus**
: Well-known open-source TypeScript projects, pinned at fixed commits in `vendor/oss/`.

**regression**
: A minimized input for a bug that is fixed, in `corpus/regressions.jsonl` (erase mode) or `corpus/downlevel.jsonl` (downlevel mode).

**finding**
: A minimized input for a bug that is still open, in `corpus/erase-findings.jsonl` or `corpus/downlevel-findings.jsonl`. When the bug is fixed, the input moves to the regression file.

**baseline**
: A list of known failures in `test/baselines/`. A failure that isn't in the baseline fails the run. A baseline entry that now passes asks you to remove it, so the list only shrinks.

## Words not to use

| Don't write | Write |
|---|---|
| strip mode, strip-only | erase mode |
| hybrid, hybrid mode, transform mode | downlevel mode |
| lite, the lite engine | the engine |
| ABI v2 | the ABI |
| ts-stripper | typestrip |
| semantic test | the erase judge (`test/erase.mjs`) |