Skip to content

Decompose the Included Files transaction into auditable modules #798

Description

@Infiland

Follow-up to #612.

Related transaction work: #718, #789, #790, #791, #792, #793.

Problem

src/conversion/included_files.py is currently 11,169 lines and its paired tests/test_included_files.py is 10,958 lines. The implementation combines source discovery, descriptor- and path-based validation, Win32/POSIX filesystem handling, tree snapshots, content receipts, staging, publication, locking, journaling, recovery, cleanup, and converter orchestration.

This code is deliberately defensive and extensively tested, but concentrating every concern in one source file and one test file makes review expensive, obscures ownership boundaries, and increases the blast radius of otherwise local changes.

Proposed scope

Refactor the Included Files implementation by responsibility after the destination-wide transaction series has stabilized. Preserve the existing converter entry point and all observable behavior while introducing cohesive internal modules with explicit dependency direction.

Acceptance criteria

  • Document the current responsibilities and an acyclic target module graph before moving behavior.
  • Keep src.conversion.included_files.IncludedFilesConverter as a thin, stable facade for existing callers.
  • Separate at least planning/models, source snapshot and verification, platform-specific filesystem operations, staging/publication, journal/recovery/cleanup, and converter orchestration.
  • Isolate POSIX descriptor operations and Windows path/reparse-point handling behind typed internal interfaces instead of allowing platform checks to spread across orchestration code.
  • Preserve generated bytes, diagnostics, cancellation behavior, locking, receipts, failure semantics, rollback, recovery, and public paths exactly.
  • Split the paired test module along the same responsibility boundaries and centralize only genuinely shared fixtures/helpers.
  • Add architecture tests that reject dependency cycles and prevent orchestration from bypassing the platform/transaction abstractions.
  • Land the refactor in reviewable behavior-preserving slices; do not combine it with new conversion features.

Verification

  • Run ./venv/bin/pyright --warnings and Ruff.
  • Run the full Python unit suite after each shared-boundary change.
  • Run the native Windows Included Files transaction workflow for Win32/junction/read-only behavior.
  • Run the pinned Godot validation relevant to Included Files output.

Non-goals

Metadata

Metadata

Assignees

No one assigned

    Labels

    architectureInternal architecture and maintainabilityassetsGameMaker asset and project importtestingTests, fixtures, CI, validation, and coverage

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions