@chappibunny/repolens 1.9.0 → 1.9.2

package/docs/CONFIGURATION.md

@@ -0,0 +1,121 @@
+# ⚙️ 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

@@ -0,0 +1,79 @@
+# 🧪 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.

package/docs/ENVIRONMENT.md

@@ -0,0 +1,57 @@
+# 🔐 Environment Variables
+
+## Notion Publisher
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NOTION_TOKEN` | Yes | Integration token from notion.so/my-integrations |
+| `NOTION_PARENT_PAGE_ID` | Yes | Page ID where docs will be created |
+| `NOTION_VERSION` | No | API version (default: `2022-06-28`) |
+
+## Confluence Publisher
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CONFLUENCE_URL` | Yes | Base URL (e.g., `https://your-company.atlassian.net/wiki`) |
+| `CONFLUENCE_EMAIL` | Yes | Atlassian account email |
+| `CONFLUENCE_API_TOKEN` | Yes | API token from [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) |
+| `CONFLUENCE_SPACE_KEY` | Yes | Target space key (e.g., `DOCS`, `ENG`) |
+| `CONFLUENCE_PARENT_PAGE_ID` | No | Parent page ID (docs created at space root if omitted) |
+
+## Discord Notifications
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DISCORD_WEBHOOK_URL` | No | Discord webhook URL for team notifications |
+
+## GitHub Wiki Publisher
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GITHUB_TOKEN` | Yes | Personal access token or Actions `${{ secrets.GITHUB_TOKEN }}` |
+| `GITHUB_REPOSITORY` | No | `owner/repo` (auto-detected from git remote in Actions) |
+
+## AI Enhancement
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `REPOLENS_AI_ENABLED` | No | Enable AI-powered sections (`true`/`false`) |
+| `REPOLENS_AI_PROVIDER` | No | Provider: `openai_compatible` (default), `anthropic`, `google`, `github` |
+| `REPOLENS_AI_API_KEY` | No | API key for AI provider (not needed for `github` provider) |
+| `REPOLENS_AI_BASE_URL` | No | API base URL (auto-set per provider; override for custom endpoints) |
+| `REPOLENS_AI_MODEL` | No | Model name (e.g., `gpt-5-mini`, `gpt-4o-mini`, `claude-sonnet-4-20250514`) |
+| `REPOLENS_AI_TEMPERATURE` | No | Generation temperature (omitted by default for GPT-5 compatibility) |
+| `REPOLENS_AI_MAX_TOKENS` | No | Max completion tokens per request (default: `2000`) |
+
+> **GitHub Models (free):** Set `REPOLENS_AI_PROVIDER=github` in GitHub Actions — uses `GITHUB_TOKEN` automatically, no separate API key required. See [AI.md](AI.md) for details.
+
+## Telemetry
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `REPOLENS_TELEMETRY_ENABLED` | No | Enable Sentry error tracking (`true`/`false`) |
+
+---
+
+**Local Development:** Create `.env` file in project root  
+**GitHub Actions:** Add as repository secrets in Settings → Secrets and variables → Actions

package/docs/INSTALLATION.md

@@ -0,0 +1,45 @@
+# 📦 Installation
+
+## Recommended: npm Registry
+
+```bash
+npm install @chappibunny/repolens
+```
+
+Installs from npm registry.
+
+## Alternative Methods
+
+<details>
+<summary><b>Option B: GitHub Direct Install</b></summary>
+
+Install from the latest GitHub commit:
+
+```bash
+npm install github:CHAPIBUNNY/repolens
+```
+</details>
+
+<details>
+<summary><b>Option C: Local Development</b></summary>
+
+Clone and link for development:
+
+```bash
+git clone https://github.com/CHAPIBUNNY/repolens.git
+cd repolens
+npm link
+```
+</details>
+
+<details>
+<summary><b>Option D: GitHub Release Tarball</b></summary>
+
+Install from a specific version:
+
+```bash
+npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v1.4.0/chappibunny-repolens-1.4.0.tgz
+```
+</details>
+
+> **Having install problems?** See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for solutions to common issues like `ENOTEMPTY`, `npm ci` failures, and stale versions.

package/docs/KNOWN_ISSUES.md

@@ -0,0 +1,309 @@
+# Known Issues & Limitations
+
+This document tracks known issues, limitations, and edge cases in RepoLens. We're committed to transparency about what works, what doesn't, and what we're working on.
+
+**Last Updated:** June 2025  
+**Version:** 1.5.0
+
+---
+
+## 🔄 Migration Tool (`repolens migrate`)
+
+### Fixed Issues (v0.4.2 - v0.4.3)
+
+These bugs were discovered in production and have been fixed:
+
+#### ✅ Duplicate `run:` Keys (Fixed in v0.4.2)
+**Symptom:** Migration created duplicate `run:` keys in workflow steps, causing YAML validation errors.
+
+**Root Cause:** Pattern insertion didn't capture existing `run:` command when adding environment variables.
+
+**Fix:** Updated regex pattern to `/(- name: .*\n)(\s+)(run:.*)/i` to capture and preserve run command.
+
+**Regression Test:** `tests/e2e/migration.test.js` includes specific test case.
+
+#### ✅ Over-Aggressive npm Install Removal (Fixed in v0.4.3)
+**Symptom:** Migration removed ALL `npm ci` and `npm install` commands, corrupting release workflows.
+
+**Root Cause:** Pattern matched any npm install, not just the legacy RepoLens-specific pattern.
+
+**Fix:** Only removes npm install from multi-line `run: |` blocks containing `cd tools/repolens`.
+
+**Pattern:** `/(run:\s*\|[^\n]*\n(?:\s+[^\n]*\n)*?\s+)npm\s+(?:ci|install)\s*\n/g`
+
+**Regression Test:** `tests/e2e/migration.test.js` includes `release-with-npm-ci.yml` fixture.
+
+### Current Limitations
+
+#### Manual Review Still Recommended
+**Issue:** While migration is highly reliable (185 tests passing), edge cases may exist in complex workflows.
+
+**Workaround:** 
+1. Run `npx @chappibunny/repolens migrate --dry-run` first
+2. Review the diff before applying
+3. Check backup files created as `*.backup`
+4. Test locally with `npx @chappibunny/repolens@latest publish`
+
+#### Multi-File Workflows Not Supported
+**Issue:** If RepoLens publish steps are split across multiple workflow files, migration may miss some.
+
+**Workaround:** Search codebase for `npx repolens` and manually update other files using the migration pattern:
+```bash
+git grep "npx repolens" .github/workflows/
+```
+
+#### Custom Environment Variable Names
+**Issue:** If you've renamed `NOTION_TOKEN` or `REPOLENS_AI_API_KEY` in your setup, migration adds the default names.
+
+**Workaround:** After migration, manually update environment variable names to match your GitHub Secrets.
+
+---
+
+## 📊 Publishing
+
+### Branch-Aware Notion Publishing
+
+#### Title Conflicts on Multi-Branch Publishing
+**Issue:** If multiple branches publish to the same Notion workspace without `.repolens.yml` → `notion.branches` filter, pages may overwrite each other.
+
+**Current Behavior:** Non-main branches get `[branch-name]` suffix to avoid collisions.
+
+**Best Practice:** Configure branch filtering in `.repolens.yml`:
+```yaml
+notion:
+  branches:
+    - main
+    - production
+```
+
+**Workaround (if not configured):** Create separate Notion pages for each branch or use branch-specific workspace IDs.
+
+#### Cache Collisions on Shared Runners
+**Issue:** GitHub Actions cache keys were not branch-scoped in early versions, causing cross-branch pollution.
+
+**Status:** Fixed in v0.4.0 (cache keys now include `${{ github.ref_name }}`).
+
+**Workaround (if using <v0.4.0):** Clear Actions cache manually in GitHub Settings → Actions → Management → Caches.
+
+### Markdown Publisher
+
+#### Large Diagrams in Markdown
+**Issue:** Unicode diagrams work well for simple architectures, but can become unwieldy for 50+ modules.
+
+**Current Behavior:** System generates box-drawing diagrams regardless of size.
+
+**Workaround:** Filter modules by domain in `.repolens.yml`:
+```yaml
+scan:
+  exclude:
+    - "**/*.test.js"
+    - "**/fixtures/**"
+```
+
+---
+
+## 🤖 AI-Assisted Documentation
+
+### Provider-Specific Issues
+
+#### OpenAI Rate Limits
+**Issue:** Free tier OpenAI accounts may hit rate limits on large repositories.
+
+**Symptom:** `Too Many Requests` errors during document generation.
+
+**Workaround:**
+1. Upgrade to OpenAI paid tier, or
+2. Use local model (Ollama) with `AI_PROVIDER=ollama`, or
+3. Run without AI enhancement (deterministic mode, no API key required)
+
+#### Anthropic Context Window Limits
+**Issue:** Claude models have 200k token limit; very large repositories may exceed this.
+
+**Symptom:** API errors about context length during synthesis.
+
+**Workaround:** Use structured context mode (default) which sends only JSON artifacts, not raw code.
+
+#### Azure OpenAI Availability
+**Issue:** Azure OpenAI requires separate deployment and endpoint configuration.
+
+**Status:** Supported but requires manual setup (see README.md).
+
+**Configuration:**
+```bash
+AI_PROVIDER=azure
+AZURE_OPENAI_API_KEY=your-key
+AZURE_OPENAI_ENDPOINT=https://your-instance.openai.azure.com/
+AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment
+```
+
+### Hallucination Prevention
+
+#### AI Context Boundaries
+**Issue:** Even with structured context, AI may occasionally make logical leaps.
+
+**Status:** Mitigated in v1.4.0 — `truncateContext()` enforces a 12K character cap with progressive field pruning.
+
+**Mitigation:** 
+- Prompts enforce word limits and require evidence-based reasoning
+- AI receives only JSON artifacts (stats, domains, modules, routes)
+- Never receives raw code to prevent fabrication
+- Deterministic fallback available (disable AI with no API key)
+
+**Best Practice:** Review generated documentation before publishing to stakeholders.
+
+---
+
+## 🔧 Configuration
+
+### Config Discovery
+
+#### Search Stops at Git Root
+**Issue:** `.repolens.yml` discovery walks up directories until hitting git root, then stops.
+
+**Impact:** If config is outside repository root, it won't be found.
+
+**Workaround:** Use `--config` flag explicitly:
+```bash
+npx @chappibunny/repolens@latest publish --config ../shared/.repolens.yml
+```
+
+#### YAML Schema Version Compatibility
+**Issue:** `configVersion: 1` required in `.repolens.yml`, but no migration tool exists yet for future version bumps.
+
+**Status:** Pre-1.0 schema changes may require manual migration.
+
+**Best Practice:** Pin to specific versions in package.json if strict stability required.
+
+---
+
+## 📦 Package Management
+
+### Scoped Package Name
+**Issue:** Package was renamed from `repolens` to `@chappibunny/repolens` due to npm name conflict.
+
+**Impact:** Old documentation may reference unscoped name.
+
+**Migration:** Use `npx @chappibunny/repolens migrate` to automatically update workflows.
+
+**Note:** Unscoped `repolens` package (v0.0.1) is a placeholder from another author.
+
+---
+
+## 🛡️ Security
+
+### Secrets in Telemetry
+**Issue:** Sentry error tracking could theoretically capture environment variables in stack traces.
+
+**Mitigation:** `beforeSend()` hook in `src/utils/telemetry.js` strips:
+- Cookies
+- Authorization headers  
+- Full file paths (sanitized to project-relative)
+- Query parameters
+
+**Best Practice:** Use `REPOLENS_TELEMETRY_ENABLED=false` (default) if handling extremely sensitive data.
+
+### GitHub Token Permissions
+**Issue:** GitHub Actions workflows need `contents: write` for PR comments, but this grants broad repository access.
+
+**Current Requirement:**
+```yaml
+permissions:
+  contents: write
+```
+
+**Planned:** Reduce to minimum required permissions:
+```yaml
+permissions:
+  contents: read
+  pull-requests: write  # Only for PR comments
+```
+
+---
+
+## 🚀 Performance
+
+### Large Repository Scanning
+**Issue:** Repositories with >10,000 files may have slow scan times.
+
+**Current Behavior:** 
+- Warning at 10k files
+- Hard failure at 50k files
+
+**Workaround:** Use `.repolens.yml` exclude patterns:
+```yaml
+scan:
+  exclude:
+    - "**/node_modules/**"
+    - "**/dist/**"
+    - "**/build/**"
+    - "**/__tests__/**"
+```
+
+### AI Generation Speed
+**Issue:** Full document generation with AI can take 2-5 minutes for large codebases.
+
+**Expected Behavior:** This is normal due to API rate limits and model processing time.
+
+**Workaround:** 
+- Use deterministic mode (no AI) for faster generation
+- Cache results in CI (already implemented via Actions cache)
+
+---
+
+## � CI/CD
+
+### macOS Lockfile on Linux Runners
+**Issue:** A `package-lock.json` generated on macOS doesn't include Linux platform-specific optional dependencies (e.g., `@rollup/rollup-linux-x64-gnu` used by Vitest/Vite).
+
+**Symptom:** `Cannot find module @rollup/rollup-linux-x64-gnu` during `npm test` in GitHub Actions.
+
+**Fix:** All CI workflows now use:
+```bash
+rm -rf node_modules package-lock.json && npm install
+```
+Do NOT use `npm ci` in GitHub Actions workflows.
+
+---
+
+## 🔮 Planned Improvements
+
+### Future
+- [ ] Obsidian vault publisher
+- [ ] Cross-repository architecture analysis
+- [ ] VS Code extension for architecture visualization
+- [ ] Slack notifications
+- [ ] Custom webhook support
+
+---
+
+## 📝 Reporting Issues
+
+If you encounter a bug not listed here:
+
+1. **Check Sentry:** If telemetry enabled, error automatically reported
+2. **GitHub Issues:** https://github.com/CHAPIBUNNY/repolens/issues
+3. **Include:**
+   - RepoLens version (`npx @chappibunny/repolens@latest version`)
+   - Node.js version (`node --version`)
+   - Operating system
+   - `.repolens.yml` config (sanitize secrets)
+   - Error message and stack trace
+   - Steps to reproduce
+
+---
+
+## 🤝 Contributing
+
+Know a workaround? Found a fix? Submit a PR:
+
+1. Fork repository
+2. Create branch: `git checkout -b fix/your-issue`
+3. Add test case to `tests/` covering the issue
+4. Implement fix
+5. Verify `npm test` passes (185 tests)
+6. Submit PR with clear description
+
+We prioritize issues with:
+- ✅ Reproducible test case
+- ✅ Clear user impact
+- ✅ Proposed solution or workaround