Migration readiness — sibling tools/ and root scripts

Survey of the 33 Python scripts in the four sibling repositories that weren’t part of the disasm_tools/ package consolidation, conducted 2026-05-01. Goal: determine how close fantasm is to subsuming the sibling tooling so the four projects can drop their bundled disasm_tools/ and (where appropriate) their workflow scripts and depend on fantasm.

Each script gets one of:

• fantasm-covered — capability is in fantasm; sibling can drop after migration.

• port-to-fantasm — generic capability worth lifting into fantasm.api; new fantasm work required.

• cli-gap — primitive exists in fantasm.api but no CLI command exposes the workflow these scripts encode.

• project-specific — stays in the sibling repo; one-off fixup, workflow orchestration, or domain-specific ingestion.

Per-script verdict

acorn-adfs/tools/

Script	Lines	Purpose	Verdict
analyse_uncommented.py	80	Cross-reference uncommented regions with named callees/callers/workspace accesses	port-to-fantasm
basic_blocks.py	211	Identify uncommented basic blocks with predecessor / successor relationships	port-to-fantasm
extract_jgh_comments.py	76	Extract block comments from J.G. Harston’s ADFS 1.30 BBC BASIC source	project-specific
extract_multitarget_symbols.py	114	Extract symbols from ld65 debug file	project-specific
find_duplicate_comments.py	82	Find doubled inline comments	fantasm-covered (comments check)
generate_labels_from_symbols.py	133	Generate label() calls from ld65 debug symbols	project-specific
import_hoglet_labels.py	90	Import labels from Hoglet’s BeebAsm disassembly	project-specific
import_multitarget_labels.py	107	Cross-reference multi-target labels against ADFS 1.30 ROM	project-specific
label_context.py	57	Extract label usage context	fantasm-covered (cfg sub + labels classify)
remove_duplicate_comments.py	119	Remove manual comments duplicating py8dis auto text	fantasm-covered (comments check)
sub_context.py	166	Extract subroutine calling-convention context	port-to-fantasm
suggest_comments.py	146	Pattern-based comment suggestions for uncommented instructions	port-to-fantasm
wksp_label_context.py	109	Workspace-label usage context	fantasm-covered (cfg sub)

acorn-econet-bridge/tools/

Script	Lines	Purpose	Verdict
find_shared_with_siblings.py	123	Find shared opcodes vs sibling-repo ROMs	fantasm-covered (shared)
refresh_shared_code.py	271	Scan all sibling ROMs, merge results into JSON	fantasm-covered (shared + project-specific orchestration)
render_shared_code.py	189	Render shared-code JSON as Markdown	project-specific

acorn-nfs/tools/

Script	Lines	Purpose	Verdict
compare_334b_vs_334.py	532	Diff annotations between two NFS versions	cli-gap
compare_annotations.py	480	Diff annotations across three NFS versions	cli-gap
compare_label_consistency.py	495	Report semantic-label inconsistencies across NFS versions	cli-gap
find_label_addresses.py	143	Map source labels to target ROM via opcode fingerprinting	cli-gap
find_stale_comments.py	222	Find comment() calls pointing to non-instruction addresses	fantasm-covered (lint)
fix_stale_comments.py	669	Resolve stale comments via opcode fingerprinting + cross-version	cli-gap (or close cousin of backfill)

acorn-nfs/ (root level)

Script	Lines	Purpose	Verdict
fix_335k_comments.py	330	Map 3.35K addresses from earlier versions via merged JSON maps	project-specific
generate_335d.py … generate_421_variant_1.py (8 scripts)	~360–530 each	Bootstrap each version’s py8dis driver from the previous version via opcode mapping	project-specific (workflow orchestration)
generate_readme.py	96	Render NFS README from Jinja template	project-specific
investigate_360.py	266	Side-by-side disassembly of UNMAPPED regions	project-specific
resolve_unmapped_340.py / resolve_unmapped_360.py	~455 each	Resolve UNMAPPED annotations via interpolation + fingerprinting	project-specific

Capability gaps

1. port-to-fantasm — new api work (4 items)

These four scripts encode genuine generic capability that fantasm hasn’t subsumed yet. All ADFS-originated, but each is project-agnostic in shape.

Capability	Sibling source	Where it would land
Uncommented-region context analysis (callees / callers / workspace accesses around uncommented gaps)	analyse_uncommented.py	fantasm.api.context.analyse_uncommented(...) + fantasm context uncommented CLI
Basic-block identification with annotation-coverage stats	basic_blocks.py	fantasm.api.cfg.basic_blocks(...) + fantasm cfg blocks CLI
Subroutine calling-convention extraction (entry, callers, exits, post-call sites)	sub_context.py	Extension to existing fantasm.api.context + fantasm cfg sub-context CLI (or fold into existing cfg sub)
Pattern-based comment suggestion for uncommented instructions	suggest_comments.py	fantasm.api.suggest (new module) + fantasm comments suggest CLI

Estimate: ~600 LOC of api code + ~150 LOC of CLI integration + tests.

2. cli-gap — exposing existing primitives (5 items)

These scripts encode workflows whose underlying primitives are already in fantasm.api. They need CLI commands, not new api work.

Workflow	Sibling source	Sketch
Cross-version annotation diff / inconsistency report	compare_334b_vs_334.py, compare_annotations.py	fantasm annotations diff V1 V2 [V3...] — uses parse_annotations + compose_chained_map + report inconsistencies
Cross-version semantic-label consistency	compare_label_consistency.py	Subset of the above, filtering auto-generated labels via fantasm.api.labels.AUTO_LABEL_RE
Pairwise address mapping export	find_label_addresses.py	fantasm addresses map SOURCE TARGET [--addrs ...] — wraps blockmatch.build_full_address_map
Comment-address rewriting via fingerprinting	fix_stale_comments.py	A fantasm backfill --apply mode or sister command that rewrites the target driver in place

Estimate: ~250 LOC of CLI + tests; no api changes needed.

3. fantasm-covered (drop after migration, ~5 items)

find_duplicate_comments.py, remove_duplicate_comments.py, label_context.py, wksp_label_context.py, find_stale_comments.py, find_shared_with_siblings.py, refresh_shared_code.py (the shared-finding part). The siblings can delete these once they switch to fantasm.

4. project-specific (~17 items)

The eleven generate_*.py driver-translation scripts, the four ADFS multi-target / Hoglet / JGH ingestion scripts, the two resolve_unmapped_*.py investigation tools, investigate_360.py, fix_335k_comments.py, render_shared_code.py, and each project’s own README generator. These stay where they are. Several of them could eventually move to fantasm with enough generalisation, but that’s a generalisation task per script, not a migration blocker.

Migration readiness verdict

Status: ready (with one optional refinement deferred). All four ports and three of four CLI gaps have landed; the remaining backfill --apply is a refinement on existing behaviour rather than a missing capability.

Closed

Item	Lands as	Status
Cross-reference uncommented gaps with cfg context (analyse_uncommented.py)	fantasm context uncommented	✅ done
Basic-block boundaries + coverage stats (basic_blocks.py)	fantasm cfg blocks	✅ done
Subroutine calling-convention extraction (sub_context.py)	fantasm cfg sub-context	✅ done
Pattern-based comment suggestions (suggest_comments.py)	fantasm comments suggest	✅ done
Cross-version annotation diff (compare_annotations.py, compare_334b_vs_334.py, compare_label_consistency.py)	fantasm annotations diff	✅ done
Pairwise address mapping export (find_label_addresses.py)	fantasm addresses map	✅ done

Deferred (not blocking)

Item	Sibling source	Notes
Driver-script comment-address rewriting	fix_stale_comments.py	fantasm backfill exists for annotation propagation; rewriting EXISTING annotations to point at corrected addresses is a different shape — closer to “apply an address map to a driver”. Worth its own design pass. The underlying primitive (blockmatch.build_full_address_map) is already exposed via fantasm addresses map, so users can pipe its output into ad-hoc scripts in the meantime.

What this means for the siblings

Each sibling can now:

1. Add fantasm as a dependency in its pyproject.toml.

2. Run fantasm project init --name <project> --prefix <prefix>... at the repo root to generate its fantasm.toml.

3. Optionally populate [memory] regions / external_regions, [[versions.entry]] entries (with parents and reloc_blocks), and per-project label hints in [comments.suggest.label_hints].

4. Delete src/disasm_tools/.

5. Update the [project.scripts] console-script entry from acorn-{x}-disasm-tool to either drop it (users invoke fantasm directly) or keep a thin shim for muscle memory.

6. Drop project-specific tools/ scripts whose capability is now in fantasm (the ~7 fantasm-covered scripts from the survey above).

The eleven generate_*.py driver-translation scripts in NFS, the ADFS ld65/Hoglet/JGH ingestion scripts, the resolve_unmapped_*.py investigators, and project-specific README generators stay in their repos — these are version-specific orchestration that doesn’t generalise.