# Turbo Modula-2 compiler re-read — project summary

Upstream inputs (local only, git-ignored): `Reversing-Turbo-Modula2-main/`
(disasm + partial decompile) and `Turbo-Modula-2-Reloaded-main/` (buildable
system). Everything below is versioned: `docs/compiler/` (analysis),
`src/compiler/` (renamed sources).

## Problem

The compiler decompiled but was unreadable: every
function/procedure/variable a bare number (`procN`/`globalN`/`paramN`/`localN`).

## Done (tags)

* `compiler-outline-v1` — `docs/compiler/00..70 + TAGGED-SUMMARY.md`:
  folder analysis, per-module architecture, full rename plan.
* `compiler-renamed-v1` — `src/compiler/COMPILER|SCANNER|ERRORS|CODEGEN.{DEF,MOD}`,
  `SYMTAB.DEF`, `README.md`, `RENAME-MAP.md`: module-level identifiers renamed
  (e.g. `InsertIdent/DeclConst/GetSym/NextChar/ReportError/FlushCodeWindow`),
  cross-module qualified uses updated, `0x1A`/`0x00` padding stripped.
* `compiler-params-v1` — all `paramN`/`localN` in the 4 `.MOD` bodies renamed
  in-scope (`kind/typeDesc/mark/sym/slot/bit/shown/desc/...`); fixed a real
  shadowing bug (`FindFileOnDrives`: local `currentDrive` shadowing the global,
  now `startDrive`); fixed missed `keywordHashFunc` and `modExtra` field.
  Verified: no numbered identifiers remain in `src/compiler/`.
* `compiler-frontend-map-v1` — `src/compiler/FRONTEND.md`: every exported head
  of `PASS1` (35), `STATEMEN` (19), `EXPRESS` (25+13 Z80 stubs) and `SYMTAB`
  bodies pinned (MCode offset + old name + proposed name + evidence), e.g.
  `~ParseType` (02e6), `ParseStatement` (0566), `ParseExpression` (1221),
  `Pass1Main` (1027). No fake signatures — map only.

## Deliberately pending

* `Pass1/Statemen/Express` bodies (disassembly only, no upstream `.MOD`).
* `SYMTAB.MOD` bodies (same).
* `GENZ80` native backend.
* Recompile + `unassemble.c` diff verification of the renamed sources.

## Next

Decompile in dependency order: `SYMTAB` (`EnterIdent/LookupChain/ImportAll`)
→ `EXPRESS` helpers → `STMT/STATSE` → `CASE/FOR` → Pass1 types → decls →
module heads → SYM writer (`docs/compiler/70-rename-plan.md`, phase 4).

## Verification status (Oct 2026, v1.00 retail toolchain + cpmulator)
Proven by recompile + MCD mnemonic diff (jump targets masked, 00-gaps
stripped; dep-slot renumbering benign, proven via slot formula):
* `COMPILER.MOD` 18/19 byte-identical (linkage names only).
* `SCANNER.MOD` 34/41 (`scanner-verify-01`; OOM was FLOAT-of-DIV expr spike,
  fixed by `1L`/`2L` folding; proc23/24 clean-room, COMPIL VarAddr shim).
* `ERRORS.MOD` 28/30 (`errors-verify-01`; heap was import weight — dropped
  unused Compiler/ComLine; EditPos module + `EDITERR` overlay load decoded).
* `CODEGEN.MOD` 34/37 (`codegen-verify-01`; keywordTable low-byte overlay).
* `SYMTAB.MOD` prefix 7/14 exact, tail by construction (`symtab-wip-04`):
  nesting per call-graph (`ee`/`ec` reproduced), record-field views, direct-
  VAR recursive arms (incl. SRC-vs-entry object fix), REPEAT loops, `i * 16`
  peephole, FindExport hoisted out. ImportAll region PROVEN uncompilable
  under v1.00-retail (6 experiments; Borland heap ~2x) — full-module
  verification awaits a bigger-heap Turbo. Genuine fixes banked (TryCompile
  logic, allocHook, view-typed params, call-graph map).
Toolchain rules proven on hardware: DEF-leak, exact DEF/MOD param names,
no FORWARD of DEF-declared procs, nominal array checks, transfer-index
and transfer-deref bans, zero-cost `CHR(ORD())`/`ORD()`/`CHR()`/`= 0`,
OOM-masking-type-errors. See SESSION.md + RENAME-MAP.md amendments.