# Inventory of `disasm_tools/` across the four sibling projects

Living document. Captures the state of the four `disasm_tools/` packages at
the time of fantasm's initial consolidation, and notes the strategy for
each module.

| Project              | path                       |
|----------------------|----------------------------|
| acorn-6502-tube-client | `src/disasm_tools/`      |
| acorn-adfs           | `src/disasm_tools/`        |
| acorn-econet-bridge  | `src/disasm_tools/`        |
| acorn-nfs            | `src/disasm_tools/`        |

All four packages share a near-identical surface, but `acorn-nfs` has
absorbed the most additions over time and is the working baseline for most
modules. A handful of modules exist in only one fork.

## Per-module status

Line counts and diff-line counts (versus NFS) collected on 2026-05-01.

| Module           | NFS | ADFS | EBR | TUBE | Status                                      | Port |
|------------------|----:|-----:|----:|-----:|---------------------------------------------|------|
| `__init__.py`    |   0 |    1 |   1 |    1 | Trivial                                     | ✅ done |
| `mos6502.py`     | 152 |   97 |  98 |   99 | NFS adds CMOS (65C02) overrides + dispatcher | ✅ done — ROM_BASE/ROM_SIZE moved out, set up for `[rom] cpu` config |
| `paths.py`       |  28 |   32 |  32 |   36 | Project-specific PREFIX; NFS supports two   | ✅ done — refactored against ProjectContext; `[versions]` config |
| `asm_extract.py` | 105 |  100 | 100 |  100 | NFS has 5 extra lines (relocation indexing) | ✅ done — typed extract_section() returning AsmSection |
| `audit.py`       | 828 |  828 | 828 |  828 | **Byte-identical**                          | ⚠️ partial — pure-logic + load_subroutines + find_undeclared_subs ported; `format_*` and top-level `audit()` deferred to CLI |
| `backfill.py`    | 621 |  621 | 621 |  621 | **Byte-identical**                          | ⚠️ partial — build_confidence_map + parse_annotations + translate_* ported; VERSION_CHAIN and chained_map deferred (NFS-specific data → fantasm.toml) |
| `cfg.py`         | 415 |  415 | 415 |  415 | NFS = ADFS = TUBE; EBR has 4 diff lines     | ⚠️ partial — build_call_graph + resolve_sub_node ported with KEY FIX (uses audit.build_memory_regions(meta), not hardcoded NFS regions); format_* deferred |
| `comment_check.py` | 677 |  677 | 677 |  677 | **Byte-identical**                        | ⚠️ partial — every check function + run_checks ported; format_findings + comment_check() deferred |
| `compare.py`     | 470 |  319 | 319 |  319 | NFS has ~150 extra lines of capability      | ✅ done — Instruction/RomHeader dataclasses, parse_rom_header, disassemble_linear, compare_roms; rom_base parameterised, "NFS" hardcode removed |
| `context.py`     | 459 |  459 | 459 |  459 | **Byte-identical**                          | ⚠️ partial — compute_call_depths ported; generate_context (file IO) deferred |
| `insert_point.py`| 183 |  183 | 183 |  183 | **Byte-identical**                          | ⚠️ partial — parse_subroutine_declarations + find_main_block + new compute_insert_point ported; print/IO wrapper deferred |
| `labels.py`      | 495 |  495 | 495 |  495 | **Byte-identical**                          | ⚠️ partial — classify_labels + sort_labels + collect_auto_labels (was `_collect_auto_labels`); generate_labels file-IO deferred |
| `lint.py`        | 555 |  522 | 522 |  492 | NFS most capable; check others for unique rules | ⚠️ partial — extract_annotations (multi-line aware, with names) + valid_addresses_from_data + address_ranges_from_data + markdown helpers ported; ROM size now a parameter; lint_*() and lint() top-level deferred |
| `rename_labels.py`| 284 |  284 | 284 |  284 | **Byte-identical**                          | ⚠️ partial — parse_label_declarations + find_rename_section + find_insert_position + new apply_renames_to_lines pure transformer; rename_labels() and show_sub_labels() file-IO deferred |
| `verify.py`      | 102 |  102 | 102 |  112 | Trivial diffs (project-name strings); TUBE has 24 extra | ✅ done — verify_round_trip() returns VerifyResult dataclass; BeebasmNotFoundError raised |
| `cli.py`         | 417 |  401 | 445 |  358 | All diverge — Click sub-commands             | ⏳ in progress — `fantasm project` group landed; rest under design |
| `promote.py`     |   – |  235 | 235 |    – | ADFS+EBR identical; not in NFS or TUBE       | ⚠️ partial — analyze_labels + load_and_analyze_labels ported; format_promote_report deferred to CLI |
| `find_shared.py` |   – |    – | 254 |    – | EBR only                                     | ⚠️ partial — sweep_opcodes / find_matching_spans / parse_rom_spec / load_rom ported; report_matches + argparse main deferred |
| `blockmatch.py`  | 299 |    – |   – |    – | NFS only                                     | ✅ done — primary + supplementary opcode mapping; rom_base parameterised |
| `fingerprint.py` | 112 |    – |   – |    – | NFS only                                     | ✅ done — opcode_fingerprint, fingerprint_blocks, find_duplicate_blocks |

### Porting strategy that emerged

For each ported module the same shape recurs: lift the pure-logic surface
into `fantasm.api.<topic>` with type hints, frozen dataclasses for results,
typed exceptions instead of `sys.exit`/stderr-print, and `warnings.warn`
for soft diagnostics. Tests are characterisation tests against
hand-crafted in-memory data — small enough to read, complete enough to
pin behaviour for refactors.

The `format_*` and file-reading top-level entry functions (the CLI side)
are intentionally deferred for each module. They will land alongside the
`fantasm <topic>` Click sub-commands in a follow-up pass, where the
project-specific strings and `rom_prefix(version_dirpath)` calls can be
threaded through a `ProjectContext` once.

Legend: NFS = `acorn-nfs`, ADFS = `acorn-adfs`, EBR = `acorn-econet-bridge`,
TUBE = `acorn-6502-tube-client`. Em-dash (`–`) means the module is absent
in that fork.

## Cross-cutting refactors

A handful of concerns appear in multiple modules and need to be lifted out
during consolidation:

- **Project layout assumptions.** `paths.py` knows the directory naming
  convention (`{PREFIX}-{version_id}/`) and the ROM-name prefix. fantasm
  expresses these in `fantasm.toml` instead of hardcoded module constants.
- **ROM bank constants.** `ROM_BASE` and `ROM_SIZE` live in `mos6502.py`
  today, but they are properties of how a ROM was *banked*, not of the
  6502. They move into `fantasm.toml` (and a future `fantasm.api.rom`
  module) so the same disassembly tools can target the BBC's 16K sideways
  ROMs, the 8K NFS sideways "half-bank", and other layouts.
- **`SystemExit` from library code.** Several siblings call `sys.exit(1)`
  on error inside library functions (e.g. `paths.resolve_version_dirpath`).
  The fantasm port raises a typed exception (e.g. `VersionNotFound`) and
  the CLI layer translates it to a clean exit code with a useful message.
- **Console-script names.** Sibling code references the project-specific
  `acorn-{x}-disasm-tool` console-script name in error messages. fantasm
  uses `fantasm`.

## Porting order

Foundational first, so later modules can build on a stable base:

1. `mos6502` (no deps; opcode tables are the bedrock)
2. `paths` (refactored against `ProjectContext` + `fantasm.toml`)
3. `labels` (used by many)
4. `comment_check`
5. `compare`
6. `audit`, `lint`, `verify`
7. `cfg`, `context`, `insert_point`
8. `rename_labels`, `asm_extract`, `backfill`
9. Specialised: `blockmatch`, `fingerprint`, `promote`, `find_shared`

CLI integration happens alongside each module: a `fantasm <topic>` group is
added with the relevant sub-commands, and the public surface is re-exported
from `fantasm.api.__init__` so callers can either `from fantasm.api import
…` or reach into `fantasm.api.<topic>`.

Tests are characterisation tests: small hand-crafted inputs whose expected
output is captured from the working code, plus round-trip tests against
`beebasm` for any module that emits assembly source.