JSPM

    ██████╗ ███████╗██████╗  ██████╗ ██╗     ███████╗███╗   ██╗███████╗
    ██╔══██╗██╔════╝██╔══██╗██╔═══██╗██║     ██╔════╝████╗  ██║██╔════╝
    ██████╔╝█████╗  ██████╔╝██║   ██║██║     █████╗  ██╔██╗ ██║███████╗
    ██╔══██╗██╔══╝  ██╔═══╝ ██║   ██║██║     ██╔══╝  ██║╚██╗██║╚════██║
    ██║  ██║███████╗██║     ╚██████╔╝███████╗███████╗██║ ╚████║███████║
    ╚═╝  ╚═╝╚══════╝╚═╝      ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═══╝╚══════╝
                        🔍 Repository Intelligence CLI 📊

AI-assisted documentation intelligence system that generates architecture docs for engineers AND readable system docs for stakeholders

Current Status: v0.4.0 — Production Ready

RepoLens automatically generates and maintains living architecture documentation by analyzing your repository structure, extracting meaningful insights from your package.json, and creating visual dependency graphs. Run it once, or let it auto-update on every push.

⚠️ Early Access Notice: The CLI commands and configuration format may evolve until v1.0. We will provide migration guides for any breaking changes. v1.0 will guarantee stable CLI behavior and config schema.

🚀 Quick Start (60 seconds)

Step 1: Install

npm install github:CHAPIBUNNY/repolens

Step 2: Initialize (creates config + GitHub Actions workflow)

npx repolens init

Step 3: Configure Notion (optional, skip if using Markdown only)

# Edit .env and add:
NOTION_TOKEN=secret_xxx
NOTION_PARENT_PAGE_ID=xxx

Step 4: Publish

npx repolens publish

Done! Your docs are now live in Notion and/or .repolens/ directory.

🔄 Upgrading from v0.3.0 or earlier? Run npx repolens migrate to automatically update your workflow files. See MIGRATION.md for details.

🎯 What RepoLens Does

RepoLens transforms repositories into documented, understandable systems with AI-assisted documentation intelligence:

🤖 Two Output Modes

Deterministic Mode (Default)

• Fast, free, always reliable
• Generates technical documentation from repository structure
• Perfect for code inventories and reference docs

AI-Enhanced Mode (Optional)

• Adds natural language explanations and insights
• Creates audience-specific documentation (technical + non-technical)
• Understands business context and data flows
• Provider-agnostic (OpenAI, Anthropic, Azure, local models)

📋 Documentation Types

Non-Technical Documents (readable by founders, PMs, ops):

• Executive Summary — Project overview, capabilities, tech summary
• Business Domains — What the system does by functional area
• Data Flows — How information moves through the system

Mixed-Audience Documents (useful for everyone):

• System Overview — Tech stack, scale, module inventory
• Developer Onboarding — How to get started contributing
• Change Impact — Architecture diff with context

Technical Documents (engineers only):

• Architecture Overview — Layered technical analysis
• Module Catalog — Complete code inventory with patterns
• API Surface — REST endpoints, methods, routes
• Route Map — Frontend routes and pages
• System Map — Visual architecture diagrams

🔍 Smart Detection

RepoLens automatically detects:

• Frameworks: Next.js, React, Vue, Express, NestJS, and more
• Languages: TypeScript, JavaScript
• Build Tools: Vite, Webpack, Turbo, esbuild
• Testing: Vitest, Jest, Playwright, Cypress
• Business Domains: Authentication, Market Data, Payments, Content, etc.
• Data Flows: How information moves through your system
• Architectural Patterns: Module relationships and dependencies

✨ Key Features

✅ AI-Assisted Documentation - Optional AI layer for natural language explanations
✅ Multi-Audience Output - Technical docs for engineers + readable docs for stakeholders
✅ Zero Hallucination Policy - AI receives only structured context, never raw code
✅ Provider Agnostic - Works with any OpenAI-compatible API
✅ Deterministic Fallback - Always generates docs even if AI unavailable
✅ Business Domain Inference - Automatically maps code to business functions
✅ Data Flow Analysis - Understands how information moves through your system
✅ Multiple Publishers - Output to Notion, Markdown, or both
✅ Branch-Aware - Prevent doc conflicts across branches
✅ GitHub Actions - Autonomous operation on every push

📦 Installation

Recommended: GitHub Install

npm install github:CHAPIBUNNY/repolens

This installs directly from the latest GitHub commit. Perfect for early access.

Alternative Methods

git clone https://github.com/CHAPIBUNNY/repolens.git
cd repolens
npm link

npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v0.2.0/repolens-0.2.0.tgz

npm install -g repolens

🎓 Complete Onboarding Guide

Step 1: Initialize RepoLens

Run this in your project root:

npx repolens init

What it creates:

• .repolens.yml — Configuration file
• .github/workflows/repolens.yml — Auto-publishing workflow
• .env.example — Environment variable template
• README.repolens.md — Quick reference guide

Default configuration works for:

• Next.js projects
• React applications
• Node.js backends
• Monorepos with common structure

Step 2: Configure Publishers

Open .repolens.yml and verify the publishers section:

publishers:
  - markdown  # Always works, no setup needed
  - notion    # Requires NOTION_TOKEN and NOTION_PARENT_PAGE_ID

Markdown Only (simplest):

publishers:
  - markdown

Documentation lands in .repolens/ directory. Commit these files or ignore them.

Notion + Markdown (recommended):

publishers:
  - notion
  - markdown

Docs published to Notion for team visibility, plus local Markdown backups.

Step 3: Enable AI Features (Optional)

AI-enhanced documentation adds natural language explanations for non-technical audiences.

3.1: Choose an AI Provider

RepoLens works with any OpenAI-compatible API:

• OpenAI (gpt-4-turbo-preview, gpt-3.5-turbo)
• Anthropic Claude (via API gateway)
• Azure OpenAI (enterprise deployments)
• Local Models (Ollama, LM Studio, etc.)

3.2: Add Environment Variables

Create .env in your project root:

# Enable AI features
REPOLENS_AI_ENABLED=true
REPOLENS_AI_API_KEY=sk-xxxxxxxxxxxxx

# Optional: Customize provider
REPOLENS_AI_BASE_URL=https://api.openai.com/v1
REPOLENS_AI_MODEL=gpt-4-turbo-preview
REPOLENS_AI_TEMPERATURE=0.3
REPOLENS_AI_MAX_TOKENS=2000

3.3: Configure AI in .repolens.yml

ai:
  enabled: true              # Enable AI features
  mode: hybrid               # hybrid, full, or off
  temperature: 0.3           # Lower = more focused (0.0-1.0)
  max_tokens: 2000           # Token limit per request

features:
  executive_summary: true    # Non-technical overview
  business_domains: true     # Functional area descriptions
  architecture_overview: true # Layered technical analysis
  data_flows: true           # System data flow explanations
  developer_onboarding: true # Getting started guide
  change_impact: true        # Architecture diff with context

Cost Estimates (with gpt-4-turbo-preview):

• Small repo (<50 files): $0.10-$0.30 per run
• Medium repo (50-200 files): $0.30-$0.80 per run
• Large repo (200+ files): $0.80-$2.00 per run

For GitHub Actions, add as repository secret:

• Name: AI_KEY, Value: sk-xxxxx (your OpenAI API key)

See AI.md for complete AI documentation and provider setup.

Step 4: Set Up Notion Integration (Optional)

If using the Notion publisher:

4.1: Create Notion Integration

1. Go to notion.so/my-integrations
2. Click "+ New Integration"
3. Name it "RepoLens"
4. Select your workspace
5. Copy the Internal Integration Token (starts with secret_)

4.2: Create Parent Page

1. Create a new page in Notion (e.g., "📚 Architecture Docs")
2. Click "..." menu → "Add connections" → Select "RepoLens"
3. Copy the page URL: https://notion.so/workspace/PAGE_ID?xxx
4. Extract the PAGE_ID (32-character hex string)

4.3: Add Environment Variables

For Local Development: Create .env in your project root:

NOTION_TOKEN=secret_xxxxxxxxxxxxx
NOTION_PARENT_PAGE_ID=xxxxxxxxxxxxx
NOTION_VERSION=2022-06-28

For GitHub Actions: Add as repository secrets:

1. Go to your repo → Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Add:
   • Name: NOTION_TOKEN, Value: secret_xxxxx
   • Name: NOTION_PARENT_PAGE_ID, Value: xxxxxx

Step 5: Configure Branch Publishing (Recommended)

Prevent documentation conflicts by limiting which branches publish to Notion:

notion:
  branches:
    - main              # Only main branch publishes
  includeBranchInTitle: false  # Clean titles (no [branch-name] suffix)

Options:

• branches: [main] — Only main publishes (recommended)
• branches: [main, staging, release/*] — Multiple branches with glob support
• Omit branches entirely — All branches publish (may cause conflicts)

Markdown publisher always runs on all branches (local files don't conflict).

Step 6: Customize Scan Patterns (Optional)

Adjust what files RepoLens scans:

scan:
  include:
    - "src/**/*.{ts,tsx,js,jsx}"
    - "app/**/*.{ts,tsx,js,jsx}"
    - "lib/**/*.{ts,tsx,js,jsx}"
  ignore:
    - "node_modules/**"
    - ".next/**"
    - "dist/**"
    - "build/**"

module_roots:
  - "src"
  - "app"
  - "lib"

Performance Note: RepoLens warns at 10k files and limits at 50k files.

Step 7: Generate Documentation

Run locally to test:

npx repolens publish

Expected output:

RepoLens v0.2.0
────────────────────────────────────────
[RepoLens] Using config: /path/to/.repolens.yml
[RepoLens] Loading configuration...
[RepoLens] Scanning repository...
[RepoLens] Detected 42 modules
[RepoLens] Publishing documentation...
[RepoLens] Publishing to Notion from branch: main
[RepoLens] ✓ System Overview published
[RepoLens] ✓ Module Catalog published
[RepoLens] ✓ API Surface published
[RepoLens] ✓ Route Map published
[RepoLens] ✓ System Map published

Step 8: Verify Output

Markdown Output:**

ls .repolens/
# system_overview.md
# module_catalog.md
# api_surface.md
# route_map.md
# system_map.md
# diagrams/system_map.svg

Notion Output: Open your Notion parent page and verify child pages were created:

• 📊 RepoLens — Executive Summary (if AI enabled)
• 📈 RepoLens — Business Domains (if AI enabled)
• 📊 RepoLens — System Overview
• 📚 RepoLens — Developer Onboarding (if AI enabled)
• 📊 RepoLens — Architecture Overview (if AI enabled)
• 📊 RepoLens — Data Flows (if AI enabled)
• 📌 RepoLens — Module Catalog
• 🔌 RepoLens — API Surface
• 🗺️ RepoLens — Route Map
• 🏛️ RepoLens — System Map

Step 9: Enable GitHub Actions (Automatic Updates)

Commit the workflow:

git add .github/workflows/repolens.yml .repolens.yml
git commit -m "Add RepoLens documentation automation"
git push

What happens next:

• ✅ Every push to main regenerates docs
• ✅ Pull requests get architecture diff comments
• ✅ Documentation stays evergreen automatically

Pro Tip: Add .repolens/ to .gitignore if you don't want to commit local Markdown files (Notion publisher is your source of truth).

🎮 Usage Commands

Publish Documentation

Auto-discovers .repolens.yml:

npx repolens publish

Specify config path explicitly:

npx repolens publish --config /path/to/.repolens.yml

Via npm script (add to package.json):

{
  "scripts": {
    "docs": "repolens publish"
  }
}

Validate Setup

Check if your RepoLens setup is valid:

npx repolens doctor

Validates:

• ✅ .repolens.yml exists and is valid YAML
• ✅ Required config fields present
• ✅ Publishers configured correctly
• ✅ Scan patterns defined
• ✅ Mermaid CLI installation status

Migrate Workflows

🚨 Upgrading from v0.3.0 or earlier? Automatically update your GitHub Actions workflows:

npx repolens migrate

Preview changes without applying:

npx repolens migrate --dry-run

What it fixes:

• ❌ Removes outdated cd tools/repolens commands
• ✅ Updates to npx repolens@latest publish
• ✅ Adds Node.js setup step if missing
• ✅ Adds environment variables (NOTION_TOKEN, REPOLENS_AI_API_KEY)
• 💾 Creates backup files for safety

Common error it fixes:

Run cd tools/repolens
cd: tools/repolens: No such file or directory
Error: Process completed with exit code 1.

See MIGRATION.md for detailed upgrade guide.

Get Help

npx repolens --help
npx repolens --version

📸 Example Output

System Map with Dependencies

graph LR
    CLI[bin/repolens<br/>1 file] --> Core[src/core<br/>3 files]
    Publishers[src/publishers<br/>4 files] --> Core
    Publishers --> Renderers[src/renderers<br/>3 files]
    Publishers --> Utils[src/utils<br/>3 files]
    Renderers --> Core
    Delivery[src/delivery<br/>1 file] --> Publishers
    Tests[tests<br/>8 files] -. tests .-> CLI
    Tests -. tests .-> Core
    Tests -. tests .-> Publishers
    
    style CLI fill:#9b59b6,color:#fff
    style Core fill:#f39c12,color:#000
    style Publishers fill:#27ae60,color:#fff
    style Renderers fill:#27ae60,color:#fff
    style Delivery fill:#16a085,color:#fff
    style Utils fill:#95a5a6,color:#000
    style Tests fill:#e67e22,color:#fff

System Overview (Technical Profile)

Generated from your package.json:

## Technical Profile

**Tech Stack**: Next.js, React  
**Languages**: TypeScript  
**Build Tools**: Vite, Turbo  
**Testing**: Vitest, Playwright  
**Architecture**: Medium-sized modular structure with 42 modules  
**API Coverage**: 18 API endpoints detected  
**UI Pages**: 25 application pages detected  

Architecture Diff in PRs

When you open a pull request, RepoLens posts:

## 📐 Architecture Diff

**Modules Changed**: 3
**New Endpoints**: 2
**Routes Modified**: 1

### New API Endpoints
- POST /api/users/:id/verify
- GET /api/users/:id/settings

### Modified Routes
- /dashboard → components/Dashboard.tsx (updated)

⚙️ Configuration Reference

Complete Example

configVersion: 1  # Schema version for future migrations

project:
  name: "my-awesome-app"
  docs_title_prefix: "MyApp"

# Configure output destinations
publishers:
  - notion
  - markdown

# Notion-specific settings (optional)
notion:
  branches:
    - main              # Only main branch publishes
    - staging           # Also staging
    - release/*         # Glob patterns supported
  includeBranchInTitle: false  # Clean titles without [branch-name]

# GitHub integration (optional)
github:
  owner: "your-username"
  repo: "your-repo-name"

# File scanning configuration
scan:
  include:
    - "src/**/*.{ts,tsx,js,jsx}"
    - "app/**/*.{ts,tsx,js,jsx}"
    - "pages/**/*.{ts,tsx,js,jsx}"
    - "lib/**/*.{ts,tsx,js,jsx}"
  ignore:
    - "node_modules/**"
    - ".next/**"
    - "dist/**"
    - "build/**"
    - "coverage/**"

# Module organization
module_roots:
  - "src"
  - "app"
  - "lib"
  - "pages"

# Documentation pages to generate
outputs:
  pages:
    - key: "system_overview"
      title: "System Overview"
      description: "High-level snapshot and tech stack"
    - key: "module_catalog"
      title: "Module Catalog"
      description: "Complete module inventory"
    - key: "api_surface"
      title: "API Surface"
      description: "REST endpoints and methods"
    - key: "route_map"
      title: "Route Map"
      description: "Frontend routes and pages"
    - key: "system_map"
      title: "System Map"
      description: "Visual dependency graph"

# Feature flags (optional, experimental)
features:
  architecture_diff: true
  route_map: true
  visual_diagrams: true

Configuration Fields

🔐 Environment Variables

Required for Notion publisher:

Local Development: Create .env file in project root
GitHub Actions: Add as repository secrets in Settings → Secrets and variables → Actions

🏗️ Architecture & Design

How RepoLens Works

1. SCAN           2. ANALYZE         3. RENDER           4. PUBLISH
──────────────────────────────────────────────────────────────────
Read files   →   Detect tech     →  Generate docs   →   Notion pages
from patterns    stack patterns      with insights       + Markdown files
                                                         + SVG diagrams

Scan Phase:

• Uses fast-glob to match your scan.include patterns
• Filters out scan.ignore patterns
• Reads package.json for framework/tool detection
• Analyzes file paths for Next.js routes, API endpoints

Analyze Phase:

• Extracts frameworks (Next.js, React, Vue, Express, etc.)
• Detects build tools (Vite, Webpack, Turbo, esbuild)
• Identifies test frameworks (Vitest, Jest, Playwright)
• Infers module relationships and dependencies

Render Phase:

• Groups files into modules based on module_roots
• Generates Mermaid diagrams showing module dependencies
• Creates technical profiles with actual stack insights
• Renders Markdown documentation

Publish Phase:

• Markdown: Writes files to .repolens/ directory
• Notion: Creates/updates pages via API with retry logic
• SVG: Generates diagrams with optional mermaid-cli
• Git: Commits diagrams back to repo for GitHub CDN hosting

Module Dependency Detection

RepoLens infers relationships by analyzing import patterns:

// In src/publishers/notion.js
import { renderSystemOverview } from "../renderers/render.js";
// → Publishers depend on Renderers

// In src/renderers/render.js  
import { scanRepo } from "../core/scan.js";
// → Renderers depend on Core

// Result: Dependency graph shows Publishers → Renderers → Core

🧪 Development

Setup

git clone https://github.com/CHAPIBUNNY/repolens.git
cd repolens
npm install
npm link  # Makes 'repolens' command available globally

Run Tests

npm test

Test Suite:

• Config discovery and validation
• Branch detection (GitHub/GitLab/CircleCI)
• Markdown publisher
• Integration workflows
• Doctor command validation

Coverage: 32 tests passing

Test Package Installation Locally

Simulates the full user installation experience:

# Pack the tarball
npm pack

# Install globally from tarball
npm install -g repolens-0.2.0.tgz

# Verify
repolens --version

Project Structure

repolens/
├── bin/
│   └── repolens.js          # CLI executable wrapper
├── src/
│   ├── cli.js               # Command orchestration + banner
│   ├── init.js              # Scaffolding command
│   ├── doctor.js            # Validation command
│   ├── core/
│   │   ├── config.js        # Config loading + validation
│   │   ├── config-schema.js # Schema version tracking
│   │   ├── diff.js          # Git diff operations
│   │   └── scan.js          # Repository scanning + metadata extraction
│   ├── renderers/
│   │   ├── render.js        # System overview, catalog, API, routes
│   │   ├── renderDiff.js    # Architecture diff rendering
│   │   └── renderMap.js     # Mermaid dependency graphs
│   ├── publishers/
│   │   ├── index.js         # Publisher orchestration + branch filtering
│   │   ├── publish.js       # Notion publishing pipeline
│   │   ├── notion.js        # Notion API integration
│   │   └── markdown.js      # Local Markdown generation
│   ├── delivery/
│   │   └── comment.js       # PR comment delivery
│   └── utils/
│       ├── logger.js        # Logging utilities
│       ├── retry.js         # API retry logic
│       ├── branch.js        # Branch detection (multi-platform)
│       └── mermaid.js       # SVG rendering + GitHub URL handling
├── tests/                   # Vitest test suite
├── .repolens.yml            # Dogfooding config
├── package.json
├── CHANGELOG.md
├── RELEASE.md
└── ROADMAP.md

🚀 Release Process

RepoLens uses automated GitHub Actions releases.

Creating a Release

# Patch version (0.2.0 → 0.2.1) - Bug fixes
npm run release:patch

# Minor version (0.2.0 → 0.3.0) - New features
npm run release:minor

# Major version (0.2.0 → 1.0.0) - Breaking changes
npm run release:major

# Push the tag to trigger workflow
git push --follow-tags

What happens:

1. ✅ All tests run
2. ✅ Package tarball created
3. ✅ GitHub Release published
4. ✅ Tarball attached as artifact

See RELEASE.md for detailed workflow.

🤝 Contributing

RepoLens is currently in early access. v1.0 will open for community contributions.

Ways to help:

• Try it out: Install and use in your projects
• Report issues: Share bugs, edge cases, or UX friction
• Request features: Tell us what's missing
• Share feedback: What works? What doesn't?

🗺️ Roadmap to v1.0

Current Status: v0.2.0 — ~92% production-ready

Completed ✅

• CLI commands: init, doctor, publish, version, help
• Config schema v1 with validation
• Auto-discovery of .repolens.yml
• Publishers: Notion + Markdown
• Branch-aware publishing with filtering
• Smart tech stack detection from package.json
• Dependency graphs with actual module relationships
• Visual diagrams with optional SVG rendering
• GitHub Actions automation
• PR architecture diff comments
• Performance guardrails (10k warning, 50k limit)
• Comprehensive test suite (32 tests)
• Interactive mermaid-cli installation

In Progress 🚧

• Production stability validation
• Enhanced error messages and debugging
• Performance optimization for large repos
• Additional framework detection (Remix, SvelteKit, Astro)

Planned for v1.0 🎯

• Plugin system for custom renderers
• GraphQL schema detection
• TypeScript type graph analysis
• Interactive configuration wizard
• Watch mode for local development
• npm registry publication

See ROADMAP.md for detailed planning.

📄 License

MIT

💬 Support & Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Contact repository maintainers