atlas-strata 0.1.0

Intelligent code analysis tool for understanding any codebase. Analyze dependencies, risks, and architecture instantly.

Atlas Strata - Code Architecture Analysis

A pure Python CLI for analyzing codebase architecture, dependencies, and code quality. Works standalone or with GitHub Copilot CLI.

Features

• Intelligent Code Analysis - Build dependency graphs automatically
• Architecture Understanding - Identify coupling, cycles, dead code, impact analysis
• Health Scoring - Rate architecture quality and surface issues
• Dependency Visualization - Interactive browser-based graphs
• Two Usage Modes - Standalone CLI for automation, Copilot CLI for exploration
• Multiple Languages - Python, TypeScript, Java, Go, C#
• JSON Export - Integration with CI/CD and other tools
• Cross-platform - Windows, macOS, Linux
• Smart Recommendations - Dual-pass analysis with AST accuracy + LLM reasoning
  • Pass 1: Precise code analysis with evidence
  • Pass 2: LLM validation (in Copilot CLI mode)

Quick Start

Installation

pip install atlas-strata

Choose Your Mode

Mode 1: Standalone (Automation-Ready)

# Quick analysis
atlas analyze .

# Generate interactive graph
atlas visualize . --format html

# Check code health
atlas health .

# Get JSON for CI/CD
atlas analyze . --format json > analysis.json

Mode 2: Copilot CLI (Interactive with LLM)

copilot: @atlas analyze --path .
copilot: What's causing high coupling?
copilot: How do I reduce it?

Common Tasks

# Find circular dependencies
atlas health cycles .

# Detect dead code
atlas health dead-code .

# Query dependency paths
atlas query --from auth.py --to main.py

# Get recommendations (AST-based)
atlas analyze . --show-evidence

# Get detailed report with recommendations
atlas report . --show-evidence

# Get recommendations with LLM reasoning (in Copilot CLI mode)
@atlas analyze . --show-evidence
@atlas report . --show-evidence

Documentation

• Standalone Mode Guide - Complete CLI reference, automation examples, CI/CD integration
• Copilot CLI Guide - Interactive queries, LLM reasoning, example conversations
• Mode Comparison - Decide which mode to use
• Command Reference - All commands documented with examples

# Check health metrics in pipeline
atlas atlas analyze . --output json --json-output metrics.json

# Generate reports for tracking
atlas atlas report . --json-output ci-report.json

Ask Complex Questions

# Interactive mode for exploration
atlas ask "what's the impact of changing auth module?" --path ./src --interactive

# Via Copilot CLI (recommended)
@atlas ask "show me all circular dependencies"

Documentation

• Getting Started - Installation and first steps
• Complete Workflow Guide - Step-by-step analysis workflow
• Real Command Outputs - Examples with actual outputs
• CLI Dependencies - Parameter analysis and execution order
• CLI Validation Report - Test results and verification
• CLI vs Copilot Integration - When to use each mode
• Installation Guide - Multiple installation methods
• API Reference - API documentation
• Architecture - System design and layers
• Recommendations Guide - Smart code quality recommendations with evidence

Commands

Standalone CLI

# Analyze directory
atlas analyze <path> [--format json|text|mermaid]

# Generate health report
atlas report <path>
atlas health <path>

# Visualize dependency graph
atlas visualize <path> [--format html|json] [--output FILE]

# Query dependencies
atlas query --from <source> --to <target> <path>

# Show help
atlas --help

Copilot CLI Integration

# Ask questions interactively
copilot: @atlas analyze --path .
copilot: @atlas visualize --path . --format json
copilot: @atlas query --from auth --to main --path .
copilot: @atlas health --path .

See Command Reference for complete documentation.

Running Tests

# Run full test suite
pytest tests/

# Run specific tests
pytest tests/test_cli.py -v

# With coverage
pytest --cov=agent tests/

Expected: 159+ tests passing

Architecture

Atlas uses a pure Python architecture:

• Core Modules: agent/atlas/core/ - Analysis engines (Analyzer, QueryEngine, Visualizer, Formatters)
• Existing Analysis Infrastructure: Reuses all existing analyzers (BlastRadius, DeadCode, Cycles, Coupling, Health)
• CLI Layer: agent/cli.py - Command-line interface using Click
• No Internal LLM: All LLM reasoning handled by Copilot CLI

No External Dependencies for LLM

• ✅ No GitHub Copilot SDK imports
• ✅ No direct API calls
• ✅ No hardcoded credentials
• ✅ Pure JSON output to stdout
• ✅ Copilot CLI manages all LLM authentication

Website

Documentation website: site/ (built with Hugo)

Key sections:

• Getting Started - Setup and first steps
• Standalone Mode - Complete CLI guide
• Copilot CLI Mode - Interactive exploration
• Mode Comparison - Choose your mode
• Command Reference - All commands documented

Development

See CONTRIBUTING.md for contribution guidelines.

Key information:

• Python 3.8+
• Pure Python execution (no subprocess calls)
• Reuse existing analysis infrastructure
• Write testable code

License

See LICENSE file.