fantasm 0.1.2__py3-none-any.whl

fantasm/__init__.py

@@ -0,0 +1,5 @@
+"""Fantasm — the Fantastic (dis-/re-)Assembly tools for 6502 code."""
+
+__version__ = "0.1.2"
+
+__all__ = ["__version__"]

fantasm/api/__init__.py

@@ -0,0 +1,240 @@
+"""Programmatic API for fantasm.
+
+Sub-modules will hold per-topic surfaces (labels, comments, cfg, audit, ...).
+This package re-exports the stable, flat surface so callers can do either:
+
+    from fantasm.api import rename_labels
+    from fantasm.api.labels import rename_labels
+
+The flat re-exports are populated as topics are ported in from the sibling
+``disasm_tools`` packages.
+"""
+
+from __future__ import annotations
+
+from .asm_extract import (
+    AsmSection,
+    build_index,
+    extract_section,
+    find_line_for_target,
+    parse_address,
+)
+from .labels import (
+    AUTO_LABEL_RE,
+    CATEGORY_ORDER,
+    build_target_refs,
+    classify_labels,
+    collect_auto_labels,
+    find_containing_sub_for_addr,
+    sort_labels,
+)
+from .cfg import (
+    BasicBlock,
+    BasicBlockEntry,
+    BasicBlockExit,
+    build_call_graph,
+    find_basic_blocks,
+    resolve_sub_node,
+)
+from .backfill import (
+    AnnotationDiff,
+    PropagationCandidate,
+    PropagationReport,
+    build_confidence_map,
+    build_confidence_map_for_block,
+    compose_chained_map,
+    diff_annotations,
+    group_logical_statements,
+    parse_annotations,
+    propose_propagations,
+    translate_address_in_text,
+    translate_subroutine,
+)
+from .blockmatch import (
+    RelocatedBlock,
+    build_full_address_map,
+    build_primary_map,
+    disassemble_to_opcodes,
+    find_relocated_blocks,
+)
+from .fingerprint import (
+    find_duplicate_blocks,
+    fingerprint_blocks,
+    fingerprint_rom_file,
+    fingerprint_window,
+    opcode_fingerprint,
+)
+from .find_shared import (
+    find_matching_spans,
+    is_trivial_span,
+    load_rom,
+    matching_byte_count,
+    parse_rom_spec,
+    sweep_opcodes,
+)
+from .suggest import (
+    CommentSuggestion,
+    DEFAULT_INSTRUCTION_HINTS,
+    suggest_comments,
+    suggest_for_instruction,
+)
+from .promote import (
+    CALL_MNEMONICS,
+    TERMINAL_MNEMONICS,
+    analyze_labels,
+    load_and_analyze_labels,
+)
+from .compare import (
+    Instruction,
+    RomHeader,
+    compare_headers,
+    compare_roms,
+    disassemble_linear,
+    format_address,
+    format_instruction,
+    parse_rom_header,
+)
+from .rename_labels import (
+    apply_renames_to_lines,
+    find_insert_position,
+    find_rename_section,
+    parse_label_declarations,
+)
+from .project import (
+    ProjectInitConfig,
+    VersionInfo,
+    add_version,
+    init_project,
+    list_versions,
+    render_fantasm_toml,
+)
+from .verify import BeebasmNotFoundError, VerifyResult, verify_round_trip
+from .version_graph import (
+    Edge,
+    NoPathError,
+    Region,
+    RelocBlock,
+    Version,
+    VersionGraph,
+    VersionGraphCycleError,
+    VersionGraphError,
+    VersionNotInGraphError,
+    load_version_graph,
+)
+from .context import (
+    CallSiteContext,
+    ExitPointContext,
+    SubContext,
+    UncommentedSubReport,
+    analyse_uncommented_subs,
+    compute_call_depths,
+    extract_sub_context,
+)
+from .lint import (
+    address_in_ranges,
+    address_ranges_from_data,
+    extract_annotations,
+    find_code_block_ranges,
+    find_nth_occurrence,
+    load_address_ranges,
+    load_valid_addresses,
+    offset_in_code_block,
+    valid_addresses_from_data,
+)
+from .insert_point import (
+    AlreadyDeclared,
+    InsertPoint,
+    compute_insert_point,
+    find_main_block,
+    parse_subroutine_declarations,
+)
+from .comment_check import (
+    ALL_CHECKS,
+    CR_ADDRESSES,
+    IMM_REG_MNEMONICS,
+    TUBE_REGISTERS,
+    build_known_addrs,
+    check_block_stale_addr,
+    check_branch_target,
+    check_chain_comments,
+    check_cr_value,
+    check_desc_stale_addr,
+    check_reg_value,
+    check_stale_addr,
+    check_tube_register,
+    find_chains,
+    find_stale_addrs,
+    parse_imm_value,
+    run_checks,
+)
+from .audit import (
+    ALL_FLAGS,
+    BRANCH_MNEMONICS,
+    TERMINATING_MNEMONICS,
+    build_memory_regions,
+    end_type,
+    find_containing_sub,
+    find_sub,
+    find_undeclared_subs,
+    load_subroutines,
+    region_for_addr,
+    scan_routine_range,
+)
+from .mos6502 import (
+    OPCODE_LENGTHS,
+    OPCODE_LENGTHS_65C02,
+    OPCODE_MNEMONICS,
+    OPCODE_MNEMONICS_65C02,
+    instruction_length,
+    mnemonic,
+    opcode_tables,
+)
+from .paths import (
+    VersionNotFoundError,
+    project_rom_prefixes,
+    project_versions_dirpath,
+    resolve_version_dirpath,
+    resolve_version_dirpath_for_project,
+    rom_prefix,
+    rom_prefix_for_project,
+)
+
+__all__ = [
+    "ALL_FLAGS",
+    "AUTO_LABEL_RE",
+    "AsmSection",
+    "BRANCH_MNEMONICS",
+    "CATEGORY_ORDER",
+    "OPCODE_LENGTHS",
+    "OPCODE_LENGTHS_65C02",
+    "OPCODE_MNEMONICS",
+    "OPCODE_MNEMONICS_65C02",
+    "TERMINATING_MNEMONICS",
+    "VersionNotFoundError",
+    "build_index",
+    "build_memory_regions",
+    "build_target_refs",
+    "classify_labels",
+    "collect_auto_labels",
+    "end_type",
+    "extract_section",
+    "find_containing_sub",
+    "find_containing_sub_for_addr",
+    "find_line_for_target",
+    "find_sub",
+    "find_undeclared_subs",
+    "instruction_length",
+    "load_subroutines",
+    "mnemonic",
+    "opcode_tables",
+    "parse_address",
+    "project_rom_prefixes",
+    "project_versions_dirpath",
+    "region_for_addr",
+    "resolve_version_dirpath",
+    "resolve_version_dirpath_for_project",
+    "rom_prefix",
+    "rom_prefix_for_project",
+    "scan_routine_range",
+    "sort_labels",
+]

fantasm/api/asm_extract.py

@@ -0,0 +1,183 @@
+"""Extract sections of a disassembly ``.asm`` file by address or label.
+
+Pure helpers for indexing assembly lines and resolving address/label
+targets. CLI-facing wrappers (file open + print) live separately.
+
+Refactors relative to the sibling copies:
+
+- :func:`find_line_for_target` no longer takes the unused ``lines``
+  parameter and emits ambiguous-match warnings via :mod:`warnings`
+  instead of printing to stderr.
+- :func:`extract_section` returns the captured slice (start line and
+  text) as a pure function; the file-based ``extract`` entry was a
+  CLI-style mixed-IO helper and has been split out so the rest of the
+  module is easier to test and re-use.
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+_ADDR_COMMENT_RE = re.compile(r";\s*([0-9a-f]{4}):")
+_RUNTIME_ADDR_RE = re.compile(r":([0-9a-f]{4})\[")
+_LABEL_RE = re.compile(r"^\.(\w+)")
+
+
+def parse_address(text: str) -> int | None:
+    """Parse a hex address in any of the conventional notations.
+
+    Recognises ``$8000``, ``&8000``, ``0x8000`` and bare ``8000``.
+    Returns ``None`` if the text is not a valid hex integer.
+    """
+    cleaned = text.strip().lstrip("$&").removeprefix("0x")
+    try:
+        return int(cleaned, 16)
+    except ValueError:
+        return None
+
+
+def build_index(
+    asm_lines: Sequence[str],
+) -> tuple[dict[int, int], dict[str, int]]:
+    """Build ``(addr_to_line, label_to_line)`` indices.
+
+    For each line, looks for a ``;NNNN:`` comment marker (the
+    disassembler's address tag) and a ``:NNNN[...]`` runtime-address
+    annotation; both are recorded in ``addr_to_line``. Lines starting
+    with ``.label`` are recorded in ``label_to_line``. The first
+    occurrence wins for any given key.
+    """
+    addr_to_line: dict[int, int] = {}
+    label_to_line: dict[str, int] = {}
+
+    for line_index, line in enumerate(asm_lines):
+        match = _ADDR_COMMENT_RE.search(line)
+        if match:
+            addr = int(match.group(1), 16)
+            addr_to_line.setdefault(addr, line_index)
+
+        match = _RUNTIME_ADDR_RE.search(line)
+        if match:
+            addr = int(match.group(1), 16)
+            addr_to_line.setdefault(addr, line_index)
+
+        match = _LABEL_RE.match(line)
+        if match:
+            label_to_line.setdefault(match.group(1), line_index)
+
+    return addr_to_line, label_to_line
+
+
+def find_line_for_target(
+    target: str,
+    addr_to_line: dict[int, int],
+    label_to_line: dict[str, int],
+) -> int | None:
+    """Resolve a textual target to a 0-based line number.
+
+    Resolution order:
+
+    1. If ``target`` parses as a hex address, return the line that maps
+       to that address — or, failing an exact match, the line for the
+       nearest indexed address less than or equal to ``target``.
+    2. If ``target`` matches a label exactly, return that label's line.
+    3. If ``target`` is a substring of exactly one label, return that
+       label's line. If it matches multiple labels, emits a
+       ``UserWarning`` listing the matches and returns the lexically
+       first match's line so callers continue to make progress.
+
+    Returns ``None`` when nothing matches.
+    """
+    addr = parse_address(target)
+    if addr is not None:
+        if addr in addr_to_line:
+            return addr_to_line[addr]
+        candidates = [a for a in addr_to_line if a <= addr]
+        if candidates:
+            return addr_to_line[max(candidates)]
+        return None
+
+    if target in label_to_line:
+        return label_to_line[target]
+
+    matches = sorted(label for label in label_to_line if target in label)
+    if not matches:
+        return None
+    if len(matches) > 1:
+        warnings.warn(
+            f"ambiguous label {target!r}; matches: {', '.join(matches)}",
+            stacklevel=2,
+        )
+    return label_to_line[matches[0]]
+
+
+@dataclass(frozen=True)
+class AsmSection:
+    """A slice of assembly lines extracted by :func:`extract_section`.
+
+    ``start_line`` and ``end_line`` are 0-based; ``end_line`` is
+    exclusive. ``lines`` is the captured text without line numbers.
+    """
+
+    start_line: int
+    end_line: int
+    lines: list[str]
+
+
+def extract_section(
+    asm_lines: Sequence[str],
+    start_target: str,
+    end_target: str | None = None,
+    default_window: int = 40,
+) -> AsmSection:
+    """Extract a section of assembly lines spanning two targets.
+
+    The section starts at the line resolved from ``start_target`` and
+    ends at the line resolved from ``end_target`` (inclusive). When no
+    ``end_target`` is given, ``default_window`` lines are taken.
+
+    The start is backed up across preceding blank, comment-only, and
+    label-only lines so the captured section includes the natural
+    "header" of the routine or block.
+
+    Raises ``LookupError`` if either target cannot be resolved.
+    """
+    addr_to_line, label_to_line = build_index(asm_lines)
+
+    start_line = find_line_for_target(start_target, addr_to_line, label_to_line)
+    if start_line is None:
+        raise LookupError(f"could not find {start_target!r}")
+
+    while start_line > 0 and not _ADDR_COMMENT_RE.search(asm_lines[start_line - 1]):
+        previous = asm_lines[start_line - 1].strip()
+        if previous == "" or previous.startswith(";") or previous.startswith("."):
+            start_line -= 1
+        else:
+            break
+
+    if end_target is not None:
+        end_line = find_line_for_target(end_target, addr_to_line, label_to_line)
+        if end_line is None:
+            raise LookupError(f"could not find {end_target!r}")
+        end_line += 1
+    else:
+        end_line = min(start_line + default_window, len(asm_lines))
+
+    return AsmSection(
+        start_line=start_line,
+        end_line=end_line,
+        lines=list(asm_lines[start_line:end_line]),
+    )
+
+
+__all__ = [
+    "AsmSection",
+    "build_index",
+    "extract_section",
+    "find_line_for_target",
+    "parse_address",
+]