@chappibunny/repolens 1.9.1 → 1.9.3

package/docs/MIGRATION.md

@@ -0,0 +1,311 @@
+# Migration Guide
+
+This guide helps you upgrade RepoLens across breaking changes and major versions.
+
+**Current Version:** 1.5.0  
+**Last Updated:** March 2026
+
+---
+
+## Migrating to v0.6.x
+
+### Package Rename
+
+The npm package was renamed from `@rabitai/repolens` to `@chappibunny/repolens` in v0.6.1.
+
+**Update your workflows:**
+```yaml
+# Old
+run: npx @rabitai/repolens@latest publish
+
+# New
+run: npx @chappibunny/repolens@latest publish
+```
+
+**Update global installs:**
+```bash
+npm uninstall -g @rabitai/repolens
+npm install -g @chappibunny/repolens
+```
+
+Or run `npx @chappibunny/repolens migrate` to auto-update workflow files.
+
+### Confluence Publisher (New in v0.6.0+)
+
+Add Confluence to your publishers if you want to publish to Atlassian Confluence:
+
+```yaml
+# .repolens.yml
+publishers:
+  - markdown
+  - notion
+  - confluence
+
+confluence:
+  branches:
+    - main
+```
+
+**Required environment variables:**
+```bash
+CONFLUENCE_URL=https://your-company.atlassian.net/wiki
+CONFLUENCE_EMAIL=trades@rabitaitrades.com
+CONFLUENCE_API_TOKEN=your-api-token
+CONFLUENCE_SPACE_KEY=DOCS
+CONFLUENCE_PARENT_PAGE_ID=123456789
+```
+
+### Dashboard Removed (v0.6.2)
+
+The interactive HTML dashboard (`renderDashboard.js`) and GitHub Pages deployment workflow (`deploy-dashboard.yml`) have been removed. If you had dashboard configuration in `.repolens.yml`, you can safely remove it:
+
+```yaml
+# Remove these if present (no longer used)
+# dashboard:
+#   enabled: true
+#   githubPages: true
+```
+
+---
+
+## Migrating from v0.3.x to v0.4.0+
+
+### Critical: Update GitHub Actions Workflow
+
+**If you see this error:**
+```
+Run cd tools/repolens
+cd: tools/repolens: No such file or directory
+```
+
+**Your workflow has an outdated format.** Run `npx @chappibunny/repolens migrate` or update manually:
+
+**Old format (v0.3.0 and earlier):**
+```yaml
+- name: Generate documentation
+  run: |
+    cd tools/repolens
+    npm install
+    npx @chappibunny/repolens publish
+```
+
+**New format (v0.4.0+):**
+```yaml
+- name: Setup Node.js
+  uses: actions/setup-node@v4
+  with:
+    node-version: 20
+
+- name: Generate and publish documentation
+  env:
+    NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
+    NOTION_PARENT_PAGE_ID: ${{ secrets.NOTION_PARENT_PAGE_ID }}
+    REPOLENS_AI_API_KEY: ${{ secrets.REPOLENS_AI_API_KEY }}
+  run: npx @chappibunny/repolens@latest publish
+```
+
+### AI Features (Optional, added in v0.4.0)
+
+AI features are opt-in. Add to `.repolens.yml`:
+
+```yaml
+ai:
+  enabled: true
+  mode: hybrid
+  max_tokens: 2500
+
+features:
+  executive_summary: true
+  business_domains: true
+  architecture_overview: true
+  data_flows: true
+  developer_onboarding: true
+  change_impact: true
+```
+
+Add a GitHub secret for your AI provider:
+```bash
+# Settings → Secrets → Actions
+REPOLENS_AI_API_KEY=sk-...
+```
+
+**Available AI document types:**
+- `executive_summary` — Non-technical project overview for leadership
+- `business_domains` — Functional area descriptions
+- `architecture_overview` — Layered technical analysis
+- `data_flows` — How information moves through the system
+- `developer_onboarding` — Getting started guide for new contributors
+- `change_impact` — Architecture diff with natural language context
+
+**Cost:** ~$0.10-$0.40 per run with gpt-5-mini
+
+### Backward Compatibility
+
+v0.4.0 is 100% backward compatible:
+- Existing `.repolens.yml` configs work without modification
+- AI features are opt-in (deterministic mode is default)
+- All 6 original document types unchanged
+- No new required dependencies
+
+---
+
+## Using the Migration Tool
+
+```bash
+# Preview changes without applying
+npx @chappibunny/repolens migrate --dry-run
+
+# Apply migration with confirmation
+npx @chappibunny/repolens migrate
+
+# Apply without confirmation
+npx @chappibunny/repolens migrate --force
+```
+
+The migration tool:
+- Auto-detects legacy patterns (`cd tools/repolens`, missing `@latest`, etc.)
+- Updates package references to `@chappibunny/repolens@latest`
+- Adds missing Node.js setup steps
+- Adds missing environment variables
+- Creates `.backup` files before modifying
+- Shows diff preview before applying
+
+---
+
+## How Updates Work
+
+### Automatic Notifications
+
+RepoLens checks for updates automatically:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                   📦 Update Available                      │
+├────────────────────────────────────────────────────────────┤
+│  Current: 0.5.0    → Latest: 1.5.0                        │
+│                                                            │
+│  Run one of these commands to update:                     │
+│                                                            │
+│  • npm install -g @chappibunny/repolens@latest (global)  │
+│  • npm install @chappibunny/repolens@latest (local)      │
+│  • npx @chappibunny/repolens@latest <command>  (latest)  │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Manual Version Check
+
+```bash
+npx @chappibunny/repolens doctor
+```
+
+### Installation Methods
+
+**GitHub Actions (recommended):**
+```yaml
+run: npx @chappibunny/repolens@latest publish
+```
+
+**Global:**
+```bash
+npm install -g @chappibunny/repolens@latest
+```
+
+**Local:**
+```bash
+npm install @chappibunny/repolens@latest
+```
+
+---
+
+## Version History
+
+### v1.2.0 (March 2026)
+- `repolens migrate` now also patches `.repolens.yml` (adds `configVersion: 1` if missing)
+- Documentation version references updated across all files
+
+### v1.1.0 (March 2026)
+- GitHub Wiki publisher with audience-grouped Home, sidebar, and page metadata
+- Temperature bug fix for GPT-5 compatibility
+
+### v1.0.1 (March 2026)
+- GPT-5 API compatibility (`max_completion_tokens`, temperature handling)
+
+### v1.0.0 (March 2026)
+- Stable release with frozen CLI, config schema, and plugin interface
+- 185 tests across 15 files
+- Semver guarantees (see STABILITY.md)
+
+### v0.9.0
+- Plugin system for custom renderers, publishers, and lifecycle hooks
+- Plugin loader, manager, and config validation
+
+### v0.8.0
+- Extended analysis: GraphQL, TypeScript type graph, dependency graph, architecture drift
+- 15 document types (4 new extended-analysis)
+
+### v0.7.0
+- Structured context builder (three-layer architecture: scan → artifacts → AI)
+- Zero-hallucination AI pipeline
+
+### v0.6.x (July 2025)
+- Confluence publisher, Discord notifications, metrics system
+- Package renamed to `@chappibunny/repolens`
+- Dashboard removed
+- CI/CD fixes for cross-platform dependency resolution
+
+### v0.5.0
+- Security hardening: secret detection, input validation, rate limiting
+- 43 security tests added (90 total)
+- GitHub Actions pinned to commit SHAs
+
+### v0.4.0
+- AI-assisted documentation (11 document types)
+- Business domain inference, data flow analysis
+- Migration tool (`repolens migrate`)
+
+### v0.3.0
+- Unicode architecture diagrams (replaced Mermaid)
+- Automatic update notifications
+- Interactive credential collection
+
+### v0.2.0
+- Branch-aware publishing, package.json metadata extraction
+- Interactive onboarding
+
+### v0.1.1
+- Initial release: `init`, `doctor`, `publish` commands
+- Notion and Markdown publishers
+
+---
+
+## Troubleshooting
+
+### Update notification not showing
+
+**Cause:** Checks are cached for 24 hours.  
+**Fix:** Run `npx @chappibunny/repolens doctor` to force a check.
+
+### "Command not found: repolens"
+
+```bash
+# Use npx (no install needed)
+npx @chappibunny/repolens@latest publish
+
+# Or install globally
+npm install -g @chappibunny/repolens@latest
+```
+
+### Old version still running after update
+
+```bash
+npm cache clean --force
+npm uninstall -g repolens
+npm install -g @chappibunny/repolens@latest
+```
+
+### GitHub Actions using old version
+
+Update workflow to use `@latest`:
+```yaml
+run: npx @chappibunny/repolens@latest publish
+```

package/docs/ONBOARDING.md

@@ -0,0 +1,382 @@
+# RepoLens — Onboarding Guide
+
+Complete step-by-step setup for RepoLens: publishers, AI enhancement, Notion, Confluence, GitHub Wiki, Discord notifications, and CI/CD automation.
+
+> **Quick start:** For a 60-second setup, see the [Quick Start](README.md#-quick-start-60-seconds) in the README.
+
+---
+
+## Step 1: Initialize RepoLens
+
+Run this in your project root:
+
+```bash
+npx @chappibunny/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:
+
+```yaml
+publishers:
+  - markdown    # Always works, no setup needed
+  - notion      # Requires NOTION_TOKEN and NOTION_PARENT_PAGE_ID
+  - confluence  # Requires CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_SPACE_KEY
+```
+
+**Markdown Only** (simplest):
+```yaml
+publishers:
+  - markdown
+```
+
+**Notion Only**:
+```yaml
+publishers:
+  - notion
+```
+
+**Confluence Only**:
+```yaml
+publishers:
+  - confluence
+```
+Documentation lands in `.repolens/` directory. Commit these files or ignore them.
+
+**Notion + Markdown** (recommended):
+```yaml
+publishers:
+  - notion
+  - markdown
+```
+Docs published to Notion for team visibility, plus local Markdown backups.
+
+**Confluence + Markdown**:
+```yaml
+publishers:
+  - confluence
+  - markdown
+```
+Docs published to Confluence for enterprise teams, plus local Markdown backups.
+
+**All Publishers**:
+```yaml
+publishers:
+  - notion
+  - confluence
+  - markdown
+```
+Maximum visibility: Notion for async collaboration, Confluence for enterprise docs, Markdown for local backups.
+
+**GitHub Wiki** (ideal for open source):
+```yaml
+publishers:
+  - github_wiki
+  - markdown
+```
+Docs live alongside your code — accessible from the repo's Wiki tab. Requires `GITHUB_TOKEN`.
+
+---
+
+## Step 3: Enable AI Features (Optional)
+
+AI-enhanced documentation adds natural language explanations for non-technical audiences.
+
+### Choose an AI Provider
+
+RepoLens works with multiple AI providers:
+- **GitHub Models** (free tier — recommended for GitHub Actions, uses `GITHUB_TOKEN`)
+- **OpenAI** (gpt-5-mini, gpt-5.4, gpt-5-nano)
+- **Anthropic Claude** (native adapter)
+- **Google Gemini** (native adapter)
+- **Azure OpenAI** (enterprise deployments)
+- **Local Models** (Ollama, LM Studio, etc.)
+
+### Option A: GitHub Models (Free — Recommended)
+
+Every GitHub repo gets free access to AI models. No API key signup needed.
+
+In your GitHub Actions workflow:
+```yaml
+env:
+  REPOLENS_AI_ENABLED: true
+  REPOLENS_AI_PROVIDER: github
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+For local development, create a [personal access token](https://github.com/settings/tokens) and add to `.env`:
+```bash
+REPOLENS_AI_ENABLED=true
+REPOLENS_AI_PROVIDER=github
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+```
+
+### Option B: OpenAI / Other Providers
+
+Create `.env` in your project root:
+```bash
+# 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-5-mini
+REPOLENS_AI_MAX_TOKENS=2000
+```
+
+### Configure AI in .repolens.yml
+
+```yaml
+ai:
+  enabled: true              # Enable AI features
+  mode: hybrid               # hybrid, full, or off
+  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-5-mini):
+- 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
+- **Free** with GitHub Models (gpt-4o-mini, rate-limited)
+
+**For GitHub Actions**, add as repository secrets:
+- For GitHub Models: no extra secrets needed — `GITHUB_TOKEN` is automatic
+- For OpenAI/other: Name: `AI_KEY`, Value: your API key
+
+See [AI.md](AI.md) for complete AI documentation and provider setup.
+
+---
+
+## Step 4: Set Up Notion Integration (Optional)
+
+### Create Notion Integration
+1. Go to [notion.so/my-integrations](https://www.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_`)
+
+### 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)
+
+### Add Environment Variables
+
+**For Local Development:**
+```bash
+NOTION_TOKEN=secret_xxxxxxxxxxxxx
+NOTION_PARENT_PAGE_ID=xxxxxxxxxxxxx
+NOTION_VERSION=2022-06-28
+```
+
+**For GitHub Actions:**
+1. Go to your repo → **Settings** → **Secrets and variables** → **Actions**
+2. Add secrets: `NOTION_TOKEN` and `NOTION_PARENT_PAGE_ID`
+
+---
+
+## Step 5: Set Up Confluence Integration (Optional)
+
+### Generate API Token
+1. Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click **"Create API token"**
+3. Name it **"RepoLens"** and copy the token
+
+### Find Your Space Key
+1. Navigate to your Confluence space
+2. Go to **Space Settings** → **Space details**
+3. Note the **Space Key** (e.g., `DOCS`, `ENG`, `TECH`)
+
+### Get Parent Page ID (Optional)
+1. Navigate to the page where you want docs nested
+2. Click **"..."** menu → **"Page information"**
+3. Copy the page ID from the URL: `pageId=123456789`
+
+### Add Environment Variables
+
+**For Local Development:**
+```bash
+CONFLUENCE_URL=https://your-company.atlassian.net/wiki
+CONFLUENCE_EMAIL=your-email@example.com
+CONFLUENCE_API_TOKEN=your-api-token-here
+CONFLUENCE_SPACE_KEY=DOCS
+CONFLUENCE_PARENT_PAGE_ID=123456789  # Optional
+```
+
+**For Confluence Server/Data Center** (self-hosted):
+```bash
+CONFLUENCE_URL=https://confluence.yourcompany.com
+CONFLUENCE_EMAIL=your-username
+CONFLUENCE_API_TOKEN=your-personal-access-token
+CONFLUENCE_SPACE_KEY=DOCS
+CONFLUENCE_PARENT_PAGE_ID=123456789  # Optional
+```
+
+**For GitHub Actions:**
+Add secrets: `CONFLUENCE_URL`, `CONFLUENCE_EMAIL`, `CONFLUENCE_API_TOKEN`, `CONFLUENCE_SPACE_KEY`, and optionally `CONFLUENCE_PARENT_PAGE_ID`.
+
+---
+
+## Step 6: Configure Branch Publishing (Recommended)
+
+Prevent documentation conflicts by limiting which branches publish:
+
+```yaml
+notion:
+  branches:
+    - main
+  includeBranchInTitle: false
+
+confluence:
+  branches:
+    - main
+```
+
+**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 7: Customize Scan Patterns (Optional)
+
+```yaml
+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 8: Generate and Verify
+
+Run locally:
+```bash
+npx @chappibunny/repolens publish
+```
+
+**Expected output:**
+```
+RepoLens 🔍
+────────────────────────────────────────────────────
+[RepoLens] Scanning repository...
+[RepoLens] Detected 42 modules
+[RepoLens] Publishing documentation...
+[RepoLens] ✓ System Overview published
+[RepoLens] ✓ Module Catalog published
+[RepoLens] ✓ API Surface published
+[RepoLens] ✓ Route Map published
+[RepoLens] ✓ System Map published
+```
+
+**Verify Markdown output:**
+```bash
+ls .repolens/
+# system_overview.md  module_catalog.md  api_surface.md  route_map.md  system_map.md
+```
+
+**Verify Notion output:**
+Open your Notion parent page and confirm child pages were created (System Overview, Module Catalog, API Surface, Route Map, System Map — plus AI documents if enabled).
+
+---
+
+## Step 9: Enable GitHub Actions
+
+Commit the workflow for automatic updates:
+```bash
+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.
+
+---
+
+## Step 10: Discord Notifications (Optional)
+
+Get notified when documentation changes significantly — rich embeds with coverage, health score, and change percentage.
+
+### Setup
+
+1. **Create a webhook** in your Discord server:
+   - Server Settings → Integrations → Webhooks → New Webhook
+   - Copy the webhook URL
+
+2. **Add to environment**:
+   ```bash
+   DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx/xxx
+   ```
+
+3. **Configure in `.repolens.yml`** (optional):
+   ```yaml
+   discord:
+     enabled: true
+     notifyOn: significant       # Options: always, significant, never
+     significantThreshold: 10    # Notify if change >10%
+     branches:
+       - main
+       - develop
+   ```
+
+4. **Add GitHub Actions secret**: `DISCORD_WEBHOOK_URL`
+
+**Notification includes:** branch info, files scanned, coverage %, health score, change %, and direct links to published docs.
+
+---
+
+## Next Steps
+
+- [Configuration Reference](CONFIGURATION.md) — Full `.repolens.yml` schema
+- [Environment Variables](ENVIRONMENT.md) — All env vars by feature
+- [Architecture](ARCHITECTURE.md) — Pipeline and project structure
+- [Security](../SECURITY.md) — Threat model and hardening details
+- [Troubleshooting](TROUBLESHOOTING.md) — Common issues and fixes