archilens 0.2.0__tar.gz

archilens-0.2.0/.archilens.yml

@@ -0,0 +1,173 @@
+# =============================================================================
+# ArchiLens Configuration
+# =============================================================================
+# This file defines how ArchiLens analyzes your repository and maps code
+# to business capabilities. Place at the root of your repository.
+
+# Project metadata
+project:
+  name: "My Application"
+  description: "Order management platform"
+  type: "microservices"  # monolith | microservices | modular-monolith | library
+
+# Analysis settings
+analysis:
+  # Languages to analyze (auto-detected if omitted)
+  languages: ["python", "typescript", "java"]
+  
+  # Entry points for process flow tracing
+  entry_points:
+    - pattern: "**/*controller*.py"
+      type: "http_handler"
+    - pattern: "**/*handler*.py"
+      type: "event_handler"
+    - pattern: "**/main.py"
+      type: "application_entry"
+    - pattern: "**/routes/**/*.ts"
+      type: "http_handler"
+
+  # Directories/patterns to exclude from analysis
+  exclude:
+    - "**/node_modules/**"
+    - "**/__pycache__/**"
+    - "**/venv/**"
+    - "**/.git/**"
+    - "**/dist/**"
+    - "**/build/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+
+  # Max depth for dependency resolution
+  max_depth: 5
+
+# Diagram generation settings
+diagrams:
+  # Output directory for generated diagrams
+  output_dir: ".archilens/diagrams"
+  
+  # Output format: mermaid | d2 | plantuml
+  format: "mermaid"
+  
+  # Diagram levels to generate
+  levels:
+    # L0: System Context - your system as a black box with external actors
+    - level: 0
+      name: "System Context"
+      enabled: true
+    
+    # L1: Module/Service Overview - major components and their relationships
+    - level: 1
+      name: "Module Architecture"
+      enabled: true
+    
+    # L2: Component Detail - internals of each module
+    - level: 2
+      name: "Component Detail"
+      enabled: true
+      # Which modules to drill into (all if omitted)
+      modules: []
+    
+    # L3: Process Flows - runtime behavior, request lifecycles
+    - level: 3
+      name: "Process Flows"
+      enabled: true
+      # Max number of flows to generate
+      max_flows: 10
+
+  # Theme for Mermaid diagrams
+  theme: "default"  # default | dark | forest | neutral
+
+# Business capability mapping
+# Maps code modules to business domains (DDD bounded contexts)
+capabilities:
+  - name: "Order Management"
+    description: "Handles order lifecycle from creation to fulfillment"
+    modules:
+      - "src/orders/**"
+      - "services/order-service/**"
+    
+  - name: "Payment Processing"
+    description: "Payment gateway integration and transaction management"
+    modules:
+      - "src/payments/**"
+      - "services/payment-service/**"
+    
+  - name: "User Management"
+    description: "Authentication, authorization, and user profiles"
+    modules:
+      - "src/auth/**"
+      - "src/users/**"
+    
+  - name: "Inventory"
+    description: "Stock tracking and warehouse management"
+    modules:
+      - "src/inventory/**"
+
+# External systems your application interacts with
+external_systems:
+  - name: "PostgreSQL"
+    type: "database"
+    description: "Primary data store"
+    
+  - name: "Redis"
+    type: "cache"
+    description: "Session and query cache"
+    
+  - name: "Stripe API"
+    type: "external_api"
+    description: "Payment processing"
+    
+  - name: "SendGrid"
+    type: "external_api"
+    description: "Email notifications"
+
+# AI configuration
+ai:
+  # Provider: anthropic | openai | ollama | litellm
+  provider: "anthropic"
+  
+  # Model to use for analysis
+  model: "claude-sonnet-4-20250514"
+  
+  # What AI should help with
+  features:
+    # Infer process flows from code that static analysis can't capture
+    process_flow_inference: true
+    # Generate natural-language annotations for diagram nodes
+    node_annotations: true
+    # Suggest business capability mappings
+    capability_suggestions: true
+    # Detect architectural patterns (MVC, hexagonal, event-driven, etc.)
+    pattern_detection: true
+    # Summarize module responsibilities
+    module_summaries: true
+
+# CI/CD integration
+ci:
+  # Run on pull requests to detect architecture drift
+  drift_detection: true
+  
+  # Comment on PRs with architecture diff
+  pr_comments: true
+  
+  # Fail the build if certain rules are violated
+  rules:
+    # Disallow direct dependencies from presentation to infrastructure
+    - name: "no-layer-skip"
+      from: "src/presentation/**"
+      to: "src/infrastructure/**"
+      action: "warn"  # warn | fail
+    
+    # Max allowed module fan-out (number of dependencies)
+    - name: "max-fan-out"
+      threshold: 10
+      action: "warn"
+
+# Evolution tracking
+evolution:
+  # Track architecture changes across Git tags/releases
+  enabled: true
+  # Compare against these refs
+  baseline_refs:
+    - "main"
+    - "tags/v*"

archilens-0.2.0/.github/workflows/archilens.yml

@@ -0,0 +1,102 @@
+# .github/workflows/archilens.yml
+# 
+# ArchiLens CI/CD Integration
+# Generates architecture diagrams on push and detects drift on PRs.
+
+name: Architecture Analysis
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  architecture:
+    name: ArchiLens Analysis
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for diff analysis
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ArchiLens
+        run: pip install archilens
+
+      # ── Generate diagrams on push to main ──
+      - name: Generate Architecture Diagrams
+        if: github.event_name == 'push'
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          archilens analyze --repo . --output .archilens/diagrams --verbose
+
+      - name: Commit Updated Diagrams
+        if: github.event_name == 'push'
+        run: |
+          git config user.name "ArchiLens Bot"
+          git config user.email "archilens[bot]@users.noreply.github.com"
+          git add .archilens/diagrams/
+          git diff --cached --quiet || git commit -m "docs: update architecture diagrams [skip ci]"
+          git push
+
+      # ── Drift detection on PRs ──
+      - name: Architecture Drift Detection
+        if: github.event_name == 'pull_request'
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          archilens diff \
+            --repo . \
+            --base origin/${{ github.base_ref }} \
+            --head HEAD \
+            > /tmp/arch-diff.md
+
+      - name: Comment PR with Architecture Changes
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let body;
+            try {
+              body = fs.readFileSync('/tmp/arch-diff.md', 'utf8');
+            } catch {
+              body = '## 🏗️ ArchiLens\n\nNo architecture changes detected.';
+            }
+            
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            
+            const existing = comments.find(c => 
+              c.body.includes('ArchiLens')
+            );
+            
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

archilens-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,viewer]"
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=archilens --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.11'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff (lint + format check)
+        run: |
+          ruff check archilens/
+          ruff format --check archilens/
+
+      - name: Mypy
+        run: mypy archilens/ --ignore-missing-imports

archilens-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write   # required for trusted publishing
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

archilens-0.2.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+
+# ArchiLens output
+.archilens/diagrams/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Claude Code project settings
+.claude/

archilens-0.2.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to ArchiLens are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.2.0] — 2026-06-10
+
+### Added
+- **MCP server** (`archilens serve-mcp`): exposes architecture knowledge to AI coding agents
+  (Claude Code, Cursor, Copilot) via four tools: `get_module_context`,
+  `check_dependency_allowed`, `find_capability_owner`, `get_architecture_context`.
+  Supports stdio and SSE transports. Snapshot cache backed by SQLite at
+  `~/.archilens/snapshots.db` — avoids re-analysis on repeated agent sessions.
+- **Cytoscape.js interactive graph** for L1 module architecture. Handles 500+ nodes
+  with compound capability groups, LOC-proportional node sizing, weighted edges,
+  click-to-drill to L2, hover tooltips, and selectable layout algorithms.
+  Mermaid retained for L2 class diagrams and L3 sequence diagrams.
+- New `/api/graph/l1` endpoint returning Cytoscape-format JSON with capability parent
+  nodes, module nodes, and weighted dependency edges.
+
+### Changed
+- **AI module**: all three analysis functions (`infer_process_flows`,
+  `generate_module_summaries`, `detect_patterns`) now use Anthropic tool use
+  (`tool_choice={"type":"tool"}`) for deterministic structured output — no more
+  JSON fence-stripping. Non-Anthropic providers retain the text-parsing fallback.
+- `generate_module_summaries` now runs up to 5 completions in parallel via
+  `ThreadPoolExecutor` — ~12x faster on large repos.
+- `ArchSnapshot.version` renamed to `project_type` to correctly store
+  `monolith|library|service` instead of a version number.
+
+### Fixed
+- Diff engine now emits `modified` entries for real signals: node LOC changes >20%
+  between refs, and edge weight (coupling) changes >20%.
+  Previously `0 modified` was always reported despite the field existing.
+- Hardcoded `your-org/archilens` link in diff markdown output replaced with correct URL.
+
+---
+
+## [0.1.0] — 2026-05-17
+
+### Added
+- Initial release
+- Core static analysis pipeline (`archilens analyze`)
+- L0–L3 Mermaid diagram generation
+- AI-powered module summaries and process flow inference
+- `archilens diff` for architecture drift detection
+- `archilens serve` for interactive web viewer
+- `archilens init` for config scaffolding
+- GitHub Action composite workflow
+- `.archilens.yml` configuration schema
+
+[Unreleased]: https://github.com/saurabh-oss/archilens/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/saurabh-oss/archilens/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/saurabh-oss/archilens/releases/tag/v0.1.0

archilens-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,147 @@
+# Contributing to ArchiLens
+
+Thank you for your interest in contributing! This guide covers everything you need to get started.
+
+## Table of Contents
+
+- [Development setup](#development-setup)
+- [Project structure](#project-structure)
+- [Running tests](#running-tests)
+- [Submitting changes](#submitting-changes)
+- [Areas for contribution](#areas-for-contribution)
+- [Code style](#code-style)
+
+---
+
+## Development Setup
+
+**Requirements**: Python 3.10+, Git
+
+```bash
+# Fork and clone
+git clone https://github.com/<your-username>/archilens.git
+cd archilens
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate      # Linux / macOS
+# .venv\Scripts\activate       # Windows
+
+# Install in editable mode with all extras
+pip install -e ".[dev,viewer]"
+```
+
+---
+
+## Project Structure
+
+```
+archilens/
+├── analyzers/       # AST extraction, dependency analysis, diff, evolution
+├── generators/      # Diagram output (Mermaid, D2, PlantUML)
+├── viewer/          # Flask interactive viewer
+├── ai/              # LLM integration (Anthropic / OpenAI / LiteLLM)
+├── models/          # Pydantic data models
+├── cli.py           # Click CLI entry point
+├── config.py        # YAML config loader
+└── engine.py        # Main analysis pipeline
+tests/
+├── test_core.py         # Core engine tests
+└── test_new_features.py # Generators, viewer, diff, evolution
+```
+
+Key data flow: `config.py` → `engine.py` → `analyzers/` → `ArchSnapshot` → `generators/` → diagrams.
+
+---
+
+## Running Tests
+
+```bash
+# Full suite with coverage
+pytest tests/ -v --cov=archilens --cov-report=term-missing
+
+# Single file
+pytest tests/test_new_features.py -v
+
+# Single test class or test
+pytest tests/test_new_features.py::TestD2Generator -v
+pytest tests/test_new_features.py::TestViewer::test_module_map_returns_sanitised_keys -v
+```
+
+All tests must pass before a PR can be merged. CI runs on Python 3.10, 3.11, and 3.12.
+
+---
+
+## Submitting Changes
+
+1. **Open an issue first** for any non-trivial change so we can discuss the approach.
+2. Create a feature branch from `master`: `git checkout -b feat/my-feature`
+3. Make your changes with tests.
+4. Run the full test suite and linters locally (see [Code style](#code-style)).
+5. Open a pull request. The CI pipeline will run automatically.
+
+### Commit message format
+
+```
+type: short description (under 72 chars)
+
+Optional longer explanation.
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`.
+
+---
+
+## Areas for Contribution
+
+### Language parsers
+Add Tree-sitter support for a new language (Ruby, Rust, C#, etc.):
+1. Add the `tree-sitter-<lang>` package to `pyproject.toml` dependencies.
+2. Add query strings to `archilens/analyzers/treesitter.py` (`_IMPORT_QUERIES`, `_CLASS_QUERIES`, `_FUNCTION_QUERIES`).
+3. Wire up the language in `_get_language()`.
+4. Add tests in `TestTreeSitter`.
+
+### Architectural pattern detection
+Patterns are detected heuristically in `archilens/engine.py` (`_detect_patterns`).
+Add a new pattern by extending the heuristic logic and the `ArchPattern` enum in `archilens/models/__init__.py`.
+
+### Diagram generators
+All generators share the `DiagramGenerator` base class in `archilens/generators/base.py`.
+To add a new format, subclass `DiagramGenerator`, implement the four abstract methods (`system_context`, `module_architecture`, `component_detail`, `process_flow`), and register it in `get_generator()`.
+
+### Interactive viewer improvements
+The viewer is a self-contained Flask app in `archilens/viewer/app.py`.
+The entire frontend is a single embedded HTML template (`_HTML_TEMPLATE`).
+
+---
+
+## Code Style
+
+```bash
+# Lint (must pass)
+ruff check archilens/
+
+# Format check (must pass)
+ruff format --check archilens/
+
+# Auto-fix formatting
+ruff format archilens/
+
+# Type checking (advisory — strict mode, warnings expected on some modules)
+mypy archilens/ --ignore-missing-imports
+```
+
+- Line length: 100
+- Target: Python 3.10+
+- No emojis in terminal output (Windows cp1252 compatibility)
+- New public functions need a one-line docstring
+- Comments only where the *why* is non-obvious
+
+---
+
+## Reporting Issues
+
+Please open an issue at https://github.com/saurabh-oss/archilens/issues with:
+- Python version and OS
+- Full error traceback
+- Minimal reproduction steps (ideally a small sample repo)

archilens-0.2.0/LICENSE

@@ -0,0 +1,15 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.