AST-based Python code analyser that maps application structure and relationships into a Neo4j graph database, with a powerful CLI for exploration and analysis.
Mapper helps you understand complex Python applications by analysing their Abstract Syntax Trees (AST) and creating an interactive graph representation of classes, functions, methods, imports, and their relationships.
- Comprehensive AST Analysis: Maps classes, functions, methods, imports, decorators, and more
- Neo4j Graph Storage: Store and query code relationships in a graph database
- Incremental Updates: Track versions and update only what changed
- CLI Tool: Powerful command-line interface built with Typer
- Risk Detection Queries: Built-in queries to find dead code, module centrality, and critical functions
- Quality Rules: Enforce type coverage, docstring coverage, and parameter complexity standards
- Package-Wide Analysis: Analyse entire Python packages from a directory
- Process Optimization: Understand complex codebases for refactoring
- Application Mapping: Visualize dependencies and relationships
- Code Navigation: Explore large applications interactively
- Impact Analysis: Trace changes through the codebase
- CLI: Typer + Rich for beautiful terminal output
- Database: Neo4j for graph storage
- Parser: Python
astmodule for code analysis - Package Manager: uv
- Task Runner: just
- Testing: pytest + pytest-mock
- Code Quality: ruff, isort, mypy
# Clone the repository
git clone git@github.com:ydkadri/mapper.git
cd mapper
# Install dependencies
just install
# Start Neo4j database
just upNeo4j will be available at:
- Neo4j Browser: http://localhost:7474 (username: neo4j, password: devpassword)
# Initialize configuration
mapper init
# Start analyzing a Python package
mapper analyse start /path/to/package
# Run risk detection queries
mapper query list # List available queries
mapper query run find-dead-code mypackage # Find unused code
mapper query run analyze-module-centrality mypackage # Find central modules
# Run quality checks (CI/CD integration)
mapper quality type-coverage mypackage # Check type hint coverage
mapper quality docstring-coverage mypackage # Check docstring coverage
mapper quality check mypackage --json # Run all quality checks
# View detailed analysis in Neo4j Browser
# Navigate to http://localhost:7474 and run Cypher queries# Development
just install # Install dependencies
just build # Build Docker containers
just up # Start Neo4j container
just down # Stop containers
just reset # Full reset (stops, removes volumes, rebuilds)
# Testing & Quality
just test # Run all tests
just test-coverage # Run tests with coverage report
just format # Format code (ruff + isort)
just lint # Run all quality checks
just fix # Auto-fix linting issues
# CLI Development
just mapper [args] # Run CLI tool locally
# Versioning
just version-show # Show current version
just version patch # Bump patch version (0.1.0 → 0.1.1)
just version minor # Bump minor version (0.1.0 → 0.2.0)
just version major # Bump major version (0.1.0 → 1.0.0)# Run all tests
just test
# Run with coverage
just test-coverage
# Run specific test file
uv run pytest tests/test_parser.py
# Run specific test
uv run pytest tests/test_parser.py::test_parse_function# Check code quality
just lint
# Format code
just format
# Fix auto-fixable issues
just fixmapper/
├── src/
│ └── mapper/ # Main package
│ ├── cli/ # CLI commands
│ ├── ast_parser/ # AST parsing
│ ├── graph_loader/ # Neo4j operations
│ ├── analyser/ # Code analysis
│ ├── query_system/ # Risk detection queries
│ ├── name_resolver/ # Name resolution
│ └── config_manager/ # Configuration management
├── tests/ # Test suite
├── docs/ # Documentation
│ ├── technical/ # Technical documentation
│ └── user-journeys/ # User journey documentation
├── .github/
│ └── workflows/ # CI/CD workflows
├── docker-compose.yml # Docker Compose configuration
├── Dockerfile # Docker image definition
├── justfile # Task runner commands
├── pyproject.toml # Project dependencies and config
├── CHANGELOG.md # Version history
├── CLAUDE.md # AI agent instructions
└── README.md # This file
# Setup
mapper init # Initialize configuration
mapper status # Check system health
mapper version # Show version
# Analysis
mapper analyse start /path/to/package # Analyze a package
mapper analyse list # List analyzed packages
mapper analyse get <package-name> # Show package details
mapper analyse export <package-name> # Export graph data
mapper analyse delete <package-name> # Delete package from database
# Configuration
mapper config get [key] # Get config value(s)
mapper config set <key> <value> # Set config value
mapper config edit # Edit config in $EDITOR
# Queries
mapper query list # List available queries
mapper query run <query-name> <package> # Run a query
mapper query create # Create custom queryAPI documentation will be available at http://localhost:8080/docs once the backend is implemented.
- Create a feature branch:
git checkout -b feature/your-feature-name - Make your changes
- Run tests and linting:
just test && just lint - Commit your changes
- Push and create a pull request
- Keep commits atomic and focused
- Write clear commit messages
- Prefer rebasing over fix commits
This project uses Semantic Versioning:
- MAJOR: Breaking changes
- MINOR: New features (backwards compatible)
- PATCH: Bug fixes (backwards compatible)
Use just version [patch|minor|major] to bump the version. Tags are created automatically by GitHub Actions on release.
- Technical Documentation: See docs/technical/
- User Journeys: See docs/user-journeys/
[Add license information here]
For issues and questions, please open a GitHub issue.