README

Atropos

Automated uses clause optimizer for Delphi projects

Atropos cleans and optimizes the uses clauses of Delphi projects (.dproj). It parses the source code to remove unused dependencies and can move dependencies from the interface to the implementation block.

Before changing any source file, Atropos builds the original project to establish a healthy baseline. It builds the project again after the optimization and either commits the operation or automatically rolls it back.

⚠️ Atropos modifies source code. Use version control, review the generated diff, and read the safety and rollback model before your first production use.

💡 Why Atropos? (Benefits)

Over time, Delphi projects accumulate "ghost dependencies": units added by the IDE or developers that are no longer used. A surgical, automated cleanup of uses clauses provides several benefits:

• ⚡ Faster compilation: The compiler parses fewer files. Moving internal dependencies to implementation also prevents unnecessary recompilation cascades.
• 📉 Smaller executables: Removing unused dependencies helps the linker discard unreachable code.
• 🧠 Better IDE performance: Cleaner dependencies reduce work for Code Insight and the Language Server Protocol.
• 🏗️ Lower coupling: Keeping implementation details out of the interface improves encapsulation and reduces dependencies between units.

⚙️ How it works

1. Project parsing: Reads the active configuration, units, and search paths from the .dproj file.
2. Healthy baseline: Locates RAD Studio and builds the original project before changing files.
3. AST analysis: Uses DelphiAST to inspect the source code and exported symbols.
4. Conservative optimization:
   • removes units that are proven to be unused;
   • moves interface dependencies used only by the implementation;
   • preserves units when the analysis cannot prove that a change is safe.
5. Transactional update: Creates backups before writing source files.
6. Build verification: Rebuilds the project and commits the changes or restores the original files.
7. Report: Shows a summary and, when requested by the CLI, writes TXT and/or HTML reports.

Units that cannot be resolved, contain initialization behavior, or use syntax that cannot be handled safely are preserved. See the known limitations for details.

🚀 Getting Started

Download the executables from the Releases page. You can use either the graphical interface (AtroposVCL.exe) or the command-line interface (AtroposCLI.exe).

Building from source

DelphiAST is tracked as a Git submodule. Clone the repository and its dependencies with:

git clone --recurse-submodules https://github.com/ViniAbreu/Atropos.git

If the repository was already cloned, initialize the dependency before building:

git submodule update --init --recursive

See the complete installation and build guide for supported tools and projects.

CLI usage

AtroposCLI.exe -dproj "C:\Projects\MyApplication\MyApplication.dproj" --remove --move -html -txt
AtroposCLI.exe -dproj "C:\Projects\MyApplication\MyApplication.dproj" --remove -txt --output reports
AtroposCLI.exe -dproj "C:\Projects\MyApplication\MyApplication.dproj" --remove --dry-run -html -txt
AtroposCLI.exe -dproj "C:\Projects\MyApplication\MyApplication.dproj" --remove --dry-run --target "Debug|Win32" --target "Debug|Win64"

Common options:

• -dproj <path>: path to the Delphi project file;
• --remove: remove dependencies proven to be unused;
• --move: move eligible dependencies from interface to implementation;
• --dry-run: report optimization candidates without modifying source files;
• --target <configuration|platform>: add a build target to the validation matrix; repeat the option to validate multiple targets;
• -html: generate an HTML report;
• -txt: generate a text report;
• --output <directory>: select the report directory;
• --debug: enable verbose logging;
• --log <file>: write a persistent UTF-8 execution log (a timestamped file under %LOCALAPPDATA%\Atropos\Logs is used by default);
• --help: display the complete command reference.

Without --remove or --move, Atropos performs the initial validation but does not request source changes. Use --dry-run to review candidates and generate reports without modifying source files. See the CLI reference for the complete contract and exit codes.

When an unqualified identifier is exported by more than one visible unit, Atropos preserves every candidate and records the reason in the TXT and HTML reports. Fully qualified references select only the named unit, allowing unrelated collisions to be removed safely.

When an external search directory cannot be scanned or an external unit cannot be parsed, Atropos preserves the unresolved dependency and records an analysis warning in the execution log and in TXT/HTML reports.

🧪 Quality and compatibility

• ✅ Automated unit and integration tests run on Win32 and Win64.
• ✅ CLI and VCL builds are validated on both architectures.
• ✅ Smoke tests exercise compilation, optimization, reporting, rollback, and representative console and VCL projects.
• ✅ Line coverage is protected by a minimum quality gate.
• ✅ DelphiAST is pinned as a Git submodule.

Consult the compatibility matrix to distinguish validated environments from versions only recognized by the resolver.

📚 Documentation

• Installation and build
• CLI reference
• VCL interface
• Safety and rollback
• Testing and coverage
• Architecture
• Compatibility
• Known limitations
• Release process

🤝 Contributing

We welcome all forms of contribution:

• 🐛 Report bugs and suggest features: open an issue.
• 💻 Submit code: read the contribution guide and open a pull request.
• ⭐️ Show support: give the project a star.
• ☕ Donate: support the project financially to help keep it active.

📄 License

GNU General Public License v3.0.