Imported from zowers/cxx_modules_converter (
AGENTS.md). Install upstream withnpx skills add zowers/cxx_modules_converter. Copyright stays with the author.
AGENTS.md - Information for AI about cxx_modules_converter project
Project Overview
cxx_modules_converter is a Python tool for converting C++ headers to C++20 modules and vice versa. The project automates migration of traditional C++ projects to modern C++20 modules.
Project Architecture
Core Components
-
CLI Interface (
cxx_modules_converter.py)- Command line argument processing
- Conversion process coordination
- Logging and statistics output
-
Core Library (
cxx_modules_converter_lib/module package)converter.py-Converterclass, main conversion logicoptions.py-Options,FileOptions,ConvertAction,ContentType, constantsresolvers.py-FilesResolver,ModuleFilesResolver,FilesMapfile_processing.py- file parsers, parsed module records, regular expressions, helper functionsfile_base_builder.py-FileBaseBuilder,FileProcessingStateheader_builder.py-HeaderBuilderfor converting parsed modules to headers and C++ sourcesmodule_base_builder.py-ModuleBaseBuilder,any_pattern_machesmodule_interface_builder.py-ModuleInterfaceUnitBuildermodule_impl_builder.py-ModuleImplUnitBuildercompat_header_builder.py-CompatHeaderBuilderexceptions.py- custom exception hierarchy__init__.py- public API exports
-
Test Infrastructure
- Modular test files with
_test.pysuffix placed next to source code test_data/- test data with input/expected structure- Test files:
module_base_builder_test.py,converter_test.py,resolvers_test.py, etc.
- Modular test files with
Key Concepts
- ContentType:
HEADER,CXX,MODULE_INTERFACE,MODULE_IMPL,OTHER - ConvertAction:
MODULES(headers → modules),HEADERS(modules → headers) - Module naming: paths converted to module names using dots (e.g.,
subdir/file.h→subdir.file)
Recommendations for AI Working on the Project
During Refactoring
-
Maintain API backward compatibility
- Don't change public class methods
- Use deprecation warnings for old APIs
- Update version in pyproject.toml
-
Test every change
- Run
pytestafter each change - Use test data from
test_data/ - Check edge cases
- Run
-
Follow code style
- Use type hints (already present)
- Naming: snake_case for functions/variables, PascalCase for classes
- Document public methods
- Use ordinary hyphen U+002d "-" (not U+2011 "‑") in all documentation and comments
-
Keep documentation current
- Remove completed tasks from TODO.md and AGENTS.md instead of marking them as done
- Delete entire sections that are no longer relevant
- Update version numbers and dates when making significant changes
When Adding Functionality
-
Extend, don't modify
- Add new parameters to
Optionswith default values - Create new classes instead of modifying existing ones
- Use inheritance for specialization
- Add new parameters to
-
Add tests
- Create test data in
test_data/new_feature/ - Write unit tests for new functionality
- Update existing tests if necessary
- Create test data in
-
Document changes
- Update README.md for new CLI features
- Add docstrings for new classes/methods
- Update usage examples
Test Data Structure
test_data/
├── test_case_name/
│ ├── input/ # Source files for conversion
│ │ ├── file1.h
│ │ └── subdir/file2.cpp
│ └── expected/ # Expected result
│ ├── file1.cppm
│ └── subdir/file2.cpp
Important: Tests compare conversion results with expected files.
Common Code Patterns
1. Processing Include Directives
if m.match(preprocessor_include_brackets_rx, line):
builder.handle_include_brackets(line, m.matched)
elif m.match(preprocessor_include_quote_rx, line):
builder.handle_include_quote(line, m.matched)
2. Building Modules
builder = ModuleInterfaceUnitBuilder(options, resolver, file_options)
builder.set_module_name(module_name)
builder.add_module_content("// implementation")
3. Converting Files
converter = Converter(ConvertAction.MODULES)
converter.options.set_root_dir_module_name("mymodule")
converter.convert_directory(input_path, output_path)
Known Limitations
- Preprocessor: Limited support for complex macros
- System Headers: Only basic transformations
- Performance: No caching, repeated file reads
- Memory: Loads all files into memory
Working Commands
Testing
# Run all tests
pytest -vv
# Run specific test
pytest cxx_modules_converter_lib/module_base_builder_test.py::test_module_empty -vv
# Run with coverage
pytest --cov=cxx_modules_converter_lib --cov-report=html
Development
# Install dependencies
pip install -r requirements-test.txt
# Run the script
python cxx_modules_converter.py -s test_data/simple/input -d output
# Type checking
mypy cxx_modules_converter.py cxx_modules_converter_lib
Code Quality Tools
# Format code with black (preserves single quotes)
python -m black .
# Sort imports with isort
python -m isort . --profile black
# Lint with flake8
python -m flake8 .
# Remove unused imports
python -m autoflake --in-place --remove-all-unused-imports cxx_modules_converter_lib/*.py
# Pre-commit hooks (install first: pip install pre-commit)
pre-commit install # Install hooks
pre-commit run --all-files # Run on all files
Contacts and Resources
- Author: Alexander Petrov (zowers@zowers.net)
- Repository: https://gitverse.ru/zowers/cxx_modules_converter
- Documentation: README.md
- Version: 0.1.17 (see pyproject.toml)
For AI Agents: How to Help the Project
- Start small: Fix one
print()orassert()usage - Test: Ensure tests pass after changes
- Document: Explain what and why was changed
- Follow the plan: See TODO.md for priorities and timelines
- Story management: All improvement stories are stored in TODO.md. New stories should be added at the end of the "Stories" section, before "Implementation Recommendations".
- Use English: Ensure all changes maintain English-only policy
Document created to assist AI agents in understanding and improving the project Version: 1.8 | Date: 2026-05-12 | Status: Current
