@chappibunny/repolens 1.12.2 → 1.13.0

package/docs/AI.md

@@ -1,329 +0,0 @@
-# AI-Enhanced Documentation
-
-As of v0.4.0, RepoLens supports AI-powered documentation generation that creates clear, audience-specific documentation for both technical and non-technical readers. This feature is available in the current version (v1.4.0).
-
-## Overview
-
-RepoLens uses a hybrid approach:
-
-1. **Deterministic extraction** - Scans your repository structure, files, routes, APIs, and technologies
-2. **Structured context** - Builds intermediate JSON artifacts with facts about your codebase
-3. **AI synthesis** - Uses LLMs to generate human-readable explanations and insights
-4. **Audience-aware output** - Creates documents for engineers, PMs, stakeholders, and executives
-
-This approach prevents hallucination while providing rich, readable documentation.
-
-## Document Structure
-
-RepoLens generates up to 15 documents:
-
-### For Non-Technical Audiences
-
-- **00-executive-summary.md** - What the system does, who it serves, key risks
-- **02-business-domains.md** - Codebase structure in business language
-
-### For Mixed Audiences
-
-- **01-system-overview.md** - High-level technical snapshot
-- **05-route-map.md** - User-facing pages and capabilities
-- **07-data-flows.md** - How information moves through the system
-- **08-change-impact.md** - PR/diff analysis in plain language
-- **09-system-map.md** - Visual diagram with explanation
-
-### For Technical Audiences
-
-- **03-architecture-overview.md** - Layered architecture analysis
-- **04-module-catalog.md** - Complete code module inventory
-- **06-api-surface.md** - Backend API documentation
-- **10-developer-onboarding.md** - Quick start for new engineers
-
-### Extended Analysis (New in v0.8.0)
-
-- **11-graphql-schema.md** - GraphQL types, queries, mutations, and resolvers
-- **12-type-graph.md** - TypeScript interfaces, classes, and type relationships
-- **13-dependency-graph.md** - Import analysis with circular dependency detection
-- **14-architecture-drift.md** - Structural changes tracked against baseline
-
-## Enabling AI Features
-
-### 1. Set Environment Variables
-
-Create a `.env` file (or set in GitHub Actions secrets):
-
-```bash
-# Enable AI features
-REPOLENS_AI_ENABLED=true
-
-# Your OpenAI API key (or compatible provider)
-REPOLENS_AI_API_KEY=sk-xxx
-
-# API endpoint (optional, defaults to OpenAI)
-REPOLENS_AI_BASE_URL=https://api.openai.com/v1
-
-# Model to use
-REPOLENS_AI_MODEL=gpt-5-mini
-```
-
-### 2. Configure in .repolens.yml
-
-```yaml
-features:
-  executive_summary: true
-  business_domains: true
-  architecture_overview: true
-  data_flows: true
-  developer_onboarding: true
-  ai_enrichment: true
-
-ai:
-  enabled: true
-  mode: "hybrid" # deterministic facts + AI explanations
-  max_tokens: 2500
-```
-
-### 3. Run Publish
-
-```bash
-npx @chappibunny/repolens publish
-```
-
-## AI Providers
-
-RepoLens supports multiple AI providers natively. Set `REPOLENS_AI_PROVIDER` to select one.
-
-### GitHub Models (Free — Recommended for GitHub Actions)
-
-Every GitHub repository gets free access to AI models via [GitHub Models](https://github.com/marketplace/models). In GitHub Actions, the `GITHUB_TOKEN` is already available — no API key signup needed.
-
-```bash
-REPOLENS_AI_ENABLED=true
-REPOLENS_AI_PROVIDER=github
-# Uses GITHUB_TOKEN automatically — no REPOLENS_AI_API_KEY needed
-# Default model: gpt-4o-mini (free tier)
-```
-
-**GitHub Actions workflow:**
-```yaml
-env:
-  REPOLENS_AI_ENABLED: true
-  REPOLENS_AI_PROVIDER: github
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-
-> **Free tier limits:** ~150 requests/day for gpt-4o-mini. RepoLens makes ~15 AI calls per run, so this is more than sufficient.
-
-### OpenAI
-
-```bash
-REPOLENS_AI_PROVIDER=openai_compatible
-REPOLENS_AI_BASE_URL=https://api.openai.com/v1
-REPOLENS_AI_API_KEY=sk-xxx
-REPOLENS_AI_MODEL=gpt-5-mini
-```
-
-### Anthropic
-
-```bash
-REPOLENS_AI_PROVIDER=anthropic
-REPOLENS_AI_API_KEY=sk-ant-xxx
-REPOLENS_AI_MODEL=claude-sonnet-4-20250514
-```
-
-### Google Gemini
-
-```bash
-REPOLENS_AI_PROVIDER=google
-REPOLENS_AI_API_KEY=xxx
-REPOLENS_AI_MODEL=gemini-pro
-```
-
-### Azure OpenAI
-
-```bash
-REPOLENS_AI_PROVIDER=openai_compatible
-REPOLENS_AI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment
-REPOLENS_AI_API_KEY=xxx
-REPOLENS_AI_MODEL=gpt-5-mini
-```
-
-### Local Models (Ollama, LM Studio, etc.)
-
-```bash
-REPOLENS_AI_PROVIDER=openai_compatible
-REPOLENS_AI_BASE_URL=http://localhost:11434/v1
-REPOLENS_AI_API_KEY=dummy # not used for local
-REPOLENS_AI_MODEL=llama3
-```
-
-## Configuration Options
-
-### AI Section
-
-```yaml
-ai:
-  enabled: true # Master switch
-  
-  mode: "hybrid" # Options: hybrid, full, off
-    # hybrid: Deterministic facts + AI explanations
-    # full: More AI-generated content
-    # off: Deterministic only
-  
-  audience_default: "mixed" # Default target audience
-    # mixed: Readable by technical and non-technical
-    # technical: Developer-focused
-    # non-technical: Leadership/stakeholder-focused
-  
-  max_tokens: 2500 # Maximum response length
-```
-
-### Business Domains
-
-Help AI understand your codebase by defining business domains:
-
-```yaml
-domains:
-  authentication:
-    match: ["auth", "login", "session"]
-    description: "User authentication flows"
-  
-  payments:
-    match: ["payment", "stripe", "checkout"]
-    description: "Payment processing"
-  
-  market_data:
-    match: ["stock", "chart", "price"]
-    description: "Financial market data"
-```
-
-### Documentation Output
-
-```yaml
-documentation:
-  output_dir: ".repolens" # Where to write files
-  include_artifacts: true # Save JSON for debugging
-  file_prefix: true # Add 00-, 01- numbers
-  
-  sections: # Which documents to generate
-    - executive_summary
-    - system_overview
-    - business_domains
-    - architecture_overview
-    - module_catalog
-    - route_map
-    - api_surface
-    - data_flows
-    - change_impact
-    - system_map
-    - developer_onboarding
-```
-
-## Cost Considerations
-
-AI generation adds cost. Typical pricing (GPT-5-mini):
-
-- Small repo (~50 modules): $0.10 - $0.30 per run
-- Medium repo (~200 modules): $0.30 - $0.80 per run
-- Large repo (~500 modules): $0.80 - $2.00 per run
-
-Tips to reduce cost:
-
-1. Use `gpt-5-nano` for faster, cheaper results
-2. Disable documents you don't need in `documentation.sections`
-3. Run on main branch only (configure `notion.branches`)
-4. Use local models for free (quality varies)
-
-## Fallback Behavior
-
-If AI is disabled or fails, RepoLens generates deterministic documentation automatically. You'll see a note: "AI-enhanced documentation is disabled."
-
-## Zero Hallucination Policy
-
-RepoLens prompts are designed to prevent AI from inventing facts:
-
-- AI receives only structured JSON context (not raw code)
-- Prompts explicitly forbid fabrication
-- AI must state uncertainty when context is insufficient
-- Deterministic facts (file counts, routes, modules) are never AI-generated
-
-## Example Outputs
-
-### Executive Summary (with AI)
-
-```markdown
-# Executive Summary
-
-## What this system does
-
-Based on the detected modules and routing structure, this appears to be 
-a financial analytics platform that combines market data visualization, 
-user account management, and research content delivery.
-
-## Who it serves
-
-The system serves retail investors and financial analysts who need...
-
-## Core capabilities
-
-1. Real-time market data analysis with interactive charts
-2. Portfolio tracking and trade management
-3. Research articles and investment insights
-...
-```
-
-### Executive Summary (without AI)
-
-```markdown
-# Executive Summary
-
-## What this system does
-
-my-project is a Next.js, React application with 271 modules across 
-1139 files.
-
-## Main system areas
-
-The codebase is organized into 12 main domains:
-- Market Data & Analysis: 45 modules
-- Authentication: 8 modules
-...
-
-Note: AI-enhanced documentation is disabled.
-```
-
-## Troubleshooting
-
-### "AI features are disabled"
-
-Set `REPOLENS_AI_ENABLED=true`
-
-### "Missing API key"
-
-Set `REPOLENS_AI_API_KEY=your-key`
-
-### "Request timeout"
-
-Increase timeout: `REPOLENS_AI_TIMEOUT_MS=120000` (2 minutes)
-
-### "Rate limit exceeded"
-
-Wait and retry, or reduce `max_tokens`
-
-### Poor quality output
-
-- Try `gpt-5.4` for highest quality output
-- Increase `max_tokens`
-- Add more detail to `domains` configuration
-
-### Running costs too high
-
-- Use `gpt-5-nano` instead of `gpt-5-mini`
-- Reduce number of documents in `documentation.sections`
-- Run less frequently (only on main branch merges)
-
-## Next Steps
-
-1. Start with default settings and `gpt-5-mini`
-2. Review generated documentation
-3. Add business domains to improve quality
-4. Adjust `max_tokens` as needed
-5. Switch to `gpt-5-nano` to reduce costs if quality is acceptable

package/docs/ARCHITECTURE.md

@@ -1,145 +0,0 @@
-# 🏗️ 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       + Confluence pages
-                                                         + Markdown files
-```
-
-**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
-- Confluence: Creates/updates pages via REST API v1 (storage format)
-
-## Module Dependency Detection
-
-RepoLens infers relationships by analyzing import patterns:
-
-```typescript
-// 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
-```
-
-## System Map
-
-```mermaid
-graph LR
-    CLI[bin/repolens<br/>1 file] --> Core[src/core<br/>4 files]
-    Publishers[src/publishers<br/>6 files] --> Core
-    Publishers --> Renderers[src/renderers<br/>4 files]
-    Publishers --> Utils[src/utils<br/>10 files]
-    Renderers --> Core
-    Delivery[src/delivery<br/>1 file] --> Publishers
-    Tests[tests<br/>15 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
-```
-
-## Project Structure
-
-```
-repolens/
-├── bin/
-│   └── repolens.js          # CLI executable wrapper
-├── src/
-│   ├── cli.js               # Command orchestration + banner
-│   ├── init.js              # Scaffolding command (+ interactive wizard)
-│   ├── doctor.js            # Validation command
-│   ├── migrate.js           # Workflow migration (legacy → current)
-│   ├── watch.js             # Watch mode for local development
-│   ├── core/
-│   │   ├── config.js        # Config loading + validation
-│   │   ├── config-schema.js # Schema version tracking
-│   │   ├── diff.js          # Git diff operations
-│   │   └── scan.js          # Repository scanning + metadata extraction
-│   ├── analyzers/
-│   │   ├── domain-inference.js    # Business domain mapping
-│   │   ├── context-builder.js     # Structured AI context assembly
-│   │   ├── flow-inference.js      # Data flow detection
-│   │   ├── graphql-analyzer.js    # GraphQL schema detection
-│   │   ├── typescript-analyzer.js # TypeScript type graph analysis
-│   │   ├── dependency-graph.js    # Import graph with cycle detection
-│   │   └── drift-detector.js      # Architecture drift detection
-│   ├── ai/
-│   │   ├── provider.js          # Provider-agnostic AI generation
-│   │   ├── prompts.js           # Strict prompt templates
-│   │   ├── document-plan.js     # Document structure definition
-│   │   └── generate-sections.js # AI section generation + fallbacks
-│   ├── docs/
-│   │   ├── generate-doc-set.js  # Document generation orchestration
-│   │   └── write-doc-set.js     # Write docs to disk
-│   ├── renderers/
-│   │   ├── render.js           # System overview, catalog, API, routes
-│   │   ├── renderDiff.js       # Architecture diff rendering
-│   │   ├── renderMap.js        # Unicode dependency diagrams
-│   │   └── renderAnalysis.js   # Extended analysis renderers
-│   ├── publishers/
-│   │   ├── index.js         # Publisher orchestration + branch filtering
-│   │   ├── publish.js       # Publishing pipeline
-│   │   ├── notion.js        # Notion API integration
-│   │   ├── confluence.js    # Confluence REST API integration
-│   │   ├── github-wiki.js   # GitHub Wiki publisher (git-based)
-│   │   └── markdown.js      # Local Markdown generation
-│   ├── integrations/
-│   │   └── discord.js       # Discord webhook notifications
-│   ├── delivery/
-│   │   └── comment.js       # PR comment delivery
-│   ├── plugins/
-│   │   ├── loader.js        # Plugin resolution and dynamic import
-│   │   └── manager.js       # Plugin registry and lifecycle orchestration
-│   └── utils/
-│       ├── logger.js        # Logging utilities
-│       ├── retry.js         # API retry logic (exponential backoff)
-│       ├── branch.js        # Branch detection (multi-platform)
-│       ├── validate.js      # Configuration validation & security
-│       ├── metrics.js       # Documentation coverage & health scoring
-│       ├── rate-limit.js    # Token bucket rate limiter for APIs
-│       ├── secrets.js       # Secret detection & sanitization
-│       ├── telemetry.js     # Opt-in error tracking + performance timers
-│       ├── errors.js        # Enhanced error messages with guidance
-│       └── update-check.js  # Version update notifications
-├── tests/                   # Vitest test suite (185 tests across 15 files)
-├── .repolens.yml            # Dogfooding config
-├── package.json
-├── CHANGELOG.md
-├── STABILITY.md
-├── RELEASE.md
-└── ROADMAP.md
-```

package/docs/CONFIGURATION.md

@@ -1,121 +0,0 @@
-# ⚙️ Configuration Reference
-
-## Complete Example
-
-```yaml
-configVersion: 1  # Schema version for future migrations
-
-project:
-  name: "my-awesome-app"
-  docs_title_prefix: "MyApp"
-
-# Configure output destinations
-publishers:
-  - notion
-  - confluence
-  - 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]
-
-# Confluence-specific settings (optional)
-confluence:
-  branches:
-    - main              # Only main branch publishes to Confluence
-
-# Discord notifications (optional)
-discord:
-  enabled: true                  # Default: true (if DISCORD_WEBHOOK_URL set)
-  notifyOn: significant          # Options: always, significant, never
-  significantThreshold: 10       # Notify if change >10% (default)
-  branches:                      # Which branches to notify (default: all)
-    - main
-    - develop
-
-# 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
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `configVersion` | number | **Yes** | Schema version (must be `1`) |
-| `project.name` | string | Yes | Project name |
-| `project.docs_title_prefix` | string | No | Prefix for documentation titles (default: project name) |
-| `publishers` | array | Yes | Output targets: `notion`, `confluence`, `github_wiki`, `markdown` (+ plugin publishers) |
-| `plugins` | array | No | Plugin paths or npm package names |
-| `notion.branches` | array | No | Branch whitelist for Notion publishing. Supports globs. |
-| `notion.includeBranchInTitle` | boolean | No | Add `[branch-name]` to titles (default: `true`) |
-| `confluence.branches` | array | No | Branch whitelist for Confluence publishing. Supports globs. |
-| `github_wiki.branches` | array | No | Branch whitelist for GitHub Wiki publishing. Supports globs. |
-| `github_wiki.sidebar` | boolean | No | Generate `_Sidebar.md` navigation (default: `true`) |
-| `github_wiki.footer` | boolean | No | Generate `_Footer.md` (default: `true`) |
-| `discord.enabled` | boolean | No | Enable Discord notifications (default: `true` if webhook set) |
-| `discord.notifyOn` | string | No | Notification policy: `always`, `significant`, `never` (default: `significant`) |
-| `discord.significantThreshold` | number | No | Change % threshold for notifications (default: `10`) |
-| `discord.branches` | array | No | Branch filter for notifications. Supports globs. (default: all) |
-| `github.owner` | string | No | GitHub org/username |
-| `github.repo` | string | No | Repository name |
-| `scan.include` | array | Yes | Glob patterns for files to scan |
-| `scan.ignore` | array | Yes | Glob patterns to exclude |
-| `module_roots` | array | No | Root directories for module detection |
-| `outputs.pages` | array | Yes | Documentation pages to generate |
-| `features` | object | No | Feature flags (boolean values) |
-| `ai.enabled` | boolean | No | Enable AI-powered documentation |
-| `ai.mode` | string | No | AI mode: `hybrid`, `full`, or `off` |
-| `ai.temperature` | number | No | Generation temperature (0–2). Not supported by all models (e.g. gpt-5-mini ignores it) |
-| `ai.max_tokens` | number | No | Max completion tokens per request (>0) |

package/docs/DEVELOPMENT.md

@@ -1,79 +0,0 @@
-# 🧪 Development
-
-## Setup
-
-```bash
-git clone https://github.com/CHAPIBUNNY/repolens.git
-cd repolens
-npm install
-npm link  # Makes 'repolens' command available globally
-```
-
-## Run Tests
-
-```bash
-npm test
-```
-
-**Test Suite:**
-- Config discovery and validation
-- Branch detection (GitHub/GitLab/CircleCI)
-- CLI commands (version, help, uninstall)
-- Markdown publisher and parser tests (Notion, Confluence)
-- Integration and HTTP integration workflows
-- Doctor command validation
-- Init wizard and scaffolding
-- AI provider and structured output tests
-- Extended analysis (GraphQL, TypeScript, dependency graph, drift)
-- Plugin system (loader, manager, config)
-- Renderers (system map, diff, analysis)
-- Deterministic enrichment (all 6 AI-enhanced doc types)
-- Security fuzzing and rate-limit stress tests
-- Watch mode and migration (including e2e)
-- Robustness (timeout, partial-publish, error isolation)
-
-**Coverage:** 380 tests passing across 22 test files
-
-## Test Package Installation Locally
-
-Simulates the full user installation experience:
-
-```bash
-# Pack the tarball
-npm pack
-
-# Install globally from tarball
-npm install -g chappibunny-repolens-1.8.1.tgz
-
-# Verify
-repolens --version
-```
-
-## Release Process
-
-RepoLens uses automated GitHub Actions releases.
-
-### Creating a Release
-
-```bash
-# Patch version (1.0.0 → 1.0.1) - Bug fixes
-npm run release:patch
-
-# Minor version (1.0.0 → 1.1.0) - New features
-npm run release:minor
-
-# Major version (1.0.0 → 2.0.0) - Breaking changes
-npm run release:major
-
-# Push the tag to trigger workflow
-git push --follow-tags
-```
-
-**What happens:**
-1. Security audit runs (dependency audit + secret scanning)
-2. All tests run
-3. Package tarball created
-4. GitHub Release published with tarball attached
-5. npm package published to `@chappibunny/repolens`
-
-See [RELEASE.md](./RELEASE.md) for detailed workflow.