@redaksjon/brennpunkt 0.0.1

package/guide/index.md

@@ -0,0 +1,177 @@
+# Brennpunkt AI Guide
+
+This directory contains comprehensive documentation designed to help AI assistants and developers understand and use Brennpunkt - a coverage priority analyzer that identifies where to focus testing efforts.
+
+## What is Brennpunkt?
+
+Brennpunkt parses `lcov.info` coverage reports and ranks files by testing priority. It answers the question: **"Where should I focus my testing efforts to have the biggest impact on coverage?"**
+
+**Core Problem Solved**: When a CI build fails with "Coverage: 85.2% < 90%", traditional reports show raw percentages but don't tell you which files will have the most impact. Brennpunkt calculates a priority score that weighs coverage gaps against file importance.
+
+## Guide Contents
+
+### Getting Started
+- [**Quick Start**](./quickstart.md): Get brennpunkt working in 2 minutes
+- [**Configuration**](./configuration.md): Config file options
+
+### Understanding Brennpunkt
+- [**Usage**](./usage.md): Complete CLI reference
+- [**Scoring**](./scoring.md): How priority scores are calculated
+- [**Integration**](./integration.md): CI/CD and workflow integration
+
+### AI & Automation
+- [**AI Integration**](./ai-integration.md): Using Brennpunkt with AI coding assistants and MCP
+
+### Development
+- [**API**](./api.md): Programmatic usage as a library
+
+## Quick Reference for AI Assistants
+
+### Essential Commands
+
+```bash
+# Basic analysis (auto-discovers coverage file)
+brennpunkt
+
+# Show top 10 priority files
+brennpunkt --top 10
+
+# JSON output for processing
+brennpunkt --json
+
+# Analyze specific coverage file
+brennpunkt path/to/lcov.info
+```
+
+### Common Tasks
+
+| Task | Command |
+|------|---------|
+| Find highest priority files | `brennpunkt --top 5` |
+| Get JSON for automation | `brennpunkt --json --top 10` |
+| Exclude tiny files | `brennpunkt --min-lines 50` |
+| Prioritize branch coverage | `brennpunkt --weights 0.7,0.2,0.1` |
+| Check configuration | `brennpunkt --check-config` |
+| Create config file | `brennpunkt --init-config` |
+
+### Coverage File Discovery
+
+Brennpunkt automatically searches these locations (in order):
+
+1. `coverage/lcov.info` - Jest, Vitest, c8 (most common)
+2. `.coverage/lcov.info` - Some configurations
+3. `coverage/lcov/lcov.info` - Karma
+4. `lcov.info` - Project root
+5. `.nyc_output/lcov.info` - NYC legacy
+6. `test-results/lcov.info` - Some CI configs
+
+### Key Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `[coverage-path]` | Path to lcov.info | Auto-discovered |
+| `-w, --weights` | Weights for branches,functions,lines | `0.5,0.3,0.2` |
+| `-m, --min-lines` | Exclude files with fewer lines | `10` |
+| `-t, --top` | Show only top N files | (all) |
+| `-j, --json` | Output as JSON | `false` |
+| `-c, --config` | Path to config file | `brennpunkt.yaml` |
+
+### Priority Score Formula
+
+```
+score = (branchGap × 0.5 + functionGap × 0.3 + lineGap × 0.2) × log₁₀(lines + 1)
+```
+
+Where:
+- `branchGap` = 100 - branch coverage %
+- `functionGap` = 100 - function coverage %
+- `lineGap` = 100 - line coverage %
+- `lines` = total lines in file
+
+**Higher score = Higher priority for testing**
+
+## For AI Assistants
+
+If you're an AI helping someone improve test coverage:
+
+1. **Run brennpunkt first**: `brennpunkt --json --top 5` to get prioritized targets
+2. **Focus on high-score files**: Files with scores > 50 need attention
+3. **Check branch coverage**: It's weighted highest (50%) because untested branches hide bugs
+4. **Use JSON output**: Parse the structured data for precise guidance
+5. **Respect project config**: Projects may have custom `brennpunkt.yaml` with different weights
+
+> **MCP Server**: Run `brennpunkt-mcp` to start an MCP server that allows AI tools to query coverage data directly without running tests. See [AI Integration](./ai-integration.md) for details.
+
+### Cursor Rule (Recommended)
+
+Add this to your project's `.cursorrules` file for automatic coverage analysis:
+
+```markdown
+# Coverage Priority Analysis
+
+When working on test coverage improvements:
+
+1. Run `npx @redaksjon/brennpunkt --json --top 5` to get prioritized files
+2. Focus on the highest priority file first (highest priorityScore)
+3. Pay special attention to:
+   - Files with low branch coverage (untested conditionals hide bugs)
+   - Files with high uncoveredLines count
+4. After writing tests, re-run brennpunkt to see updated priorities
+
+When I ask about test coverage, run brennpunkt and interpret the results.
+Suggest specific test cases based on the uncovered branches and functions.
+```
+
+Then just ask: "What files need test coverage?" or "Help me improve test coverage"
+
+### Example Workflow
+
+```bash
+# Step 1: Get priority list
+brennpunkt --json --top 3
+
+# Step 2: AI receives structured data like:
+{
+  "files": [
+    {
+      "file": "src/auth/login.ts",
+      "priorityScore": 156.3,
+      "uncoveredBranches": 13,
+      "uncoveredLines": 45
+    }
+  ]
+}
+
+# Step 3: Write tests for src/auth/login.ts focusing on the 13 untested branches
+```
+
+## Configuration File
+
+Create `brennpunkt.yaml` in your project root:
+
+```yaml
+# Priority weights (branches, functions, lines)
+weights: "0.5,0.3,0.2"
+
+# Minimum lines for inclusion
+minLines: 10
+
+# Limit results
+top: 20
+
+# Output format
+json: false
+```
+
+## npm Post-Test Integration
+
+Add to `package.json` for automatic analysis:
+
+```json
+{
+  "scripts": {
+    "test": "vitest run --coverage",
+    "posttest": "brennpunkt --top 10"
+  }
+}
+```

package/guide/integration.md

@@ -0,0 +1,283 @@
+# CI/CD Integration
+
+How to integrate brennpunkt into your development workflow and CI pipelines.
+
+## npm Post-Test Hook
+
+The simplest integration - run brennpunkt automatically after every test:
+
+```json
+{
+  "scripts": {
+    "test": "vitest run --coverage",
+    "posttest": "brennpunkt --top 10"
+  }
+}
+```
+
+Now `npm test` automatically shows coverage priorities:
+
+```bash
+$ npm test
+
+✓ tests/auth.test.ts (15 tests)
+✓ tests/api.test.ts (23 tests)
+
+Coverage: 85.2%
+
+Using coverage file: coverage/lcov.info
+
+📊 Coverage Priority Report
+...
+🎯 Recommended Focus (Top 3):
+  1. src/auth/login.ts - 13 untested branches
+```
+
+## GitHub Actions
+
+### Basic Integration
+
+Add to your test workflow:
+
+```yaml
+name: Test & Coverage
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - run: npm ci
+      - run: npm test -- --coverage
+      
+      # Add coverage priority analysis
+      - name: Coverage Priority Analysis
+        run: npx @redaksjon/brennpunkt --top 10
+```
+
+### Save JSON Artifact
+
+Store the priority report for later analysis:
+
+```yaml
+      - name: Generate Priority Report
+        run: npx @redaksjon/brennpunkt --json > coverage-priority.json
+      
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-priority
+          path: coverage-priority.json
+```
+
+### PR Comment
+
+Post coverage priorities as a PR comment:
+
+```yaml
+      - name: Coverage Priority Analysis
+        id: coverage
+        run: |
+          OUTPUT=$(npx @redaksjon/brennpunkt --top 5 2>&1)
+          echo "report<<EOF" >> $GITHUB_OUTPUT
+          echo "$OUTPUT" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Comment on PR
+        uses: actions/github-script@v7
+        if: github.event_name == 'pull_request'
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: '## Coverage Priority Analysis\n\n```\n${{ steps.coverage.outputs.report }}\n```'
+            })
+```
+
+## GitLab CI
+
+```yaml
+test:
+  stage: test
+  script:
+    - npm ci
+    - npm test -- --coverage
+    - npx @redaksjon/brennpunkt --top 10
+  artifacts:
+    reports:
+      coverage_report:
+        coverage_format: cobertura
+        path: coverage/cobertura-coverage.xml
+    paths:
+      - coverage-priority.json
+    when: always
+```
+
+## Jenkins
+
+```groovy
+pipeline {
+    agent any
+    stages {
+        stage('Test') {
+            steps {
+                sh 'npm ci'
+                sh 'npm test -- --coverage'
+                sh 'npx @redaksjon/brennpunkt --top 10'
+            }
+        }
+        stage('Coverage Report') {
+            steps {
+                sh 'npx @redaksjon/brennpunkt --json > coverage-priority.json'
+                archiveArtifacts artifacts: 'coverage-priority.json'
+            }
+        }
+    }
+}
+```
+
+## CircleCI
+
+```yaml
+version: 2.1
+jobs:
+  test:
+    docker:
+      - image: cimg/node:20.0
+    steps:
+      - checkout
+      - run: npm ci
+      - run: npm test -- --coverage
+      - run: npx @redaksjon/brennpunkt --top 10
+      - store_artifacts:
+          path: coverage
+          destination: coverage
+```
+
+## Quality Gates
+
+### Fail on High-Priority Gaps
+
+Block builds when critical files have unacceptable coverage:
+
+```bash
+#!/bin/bash
+# scripts/coverage-gate.sh
+
+# Get the highest priority score
+TOP_SCORE=$(npx @redaksjon/brennpunkt --json --top 1 | jq '.files[0].priorityScore // 0')
+
+echo "Top priority score: $TOP_SCORE"
+
+# Fail if score exceeds threshold
+if (( $(echo "$TOP_SCORE > 100" | bc -l) )); then
+  echo "❌ High-priority coverage gap detected (score: $TOP_SCORE)"
+  echo ""
+  echo "Files needing attention:"
+  npx @redaksjon/brennpunkt --top 5
+  exit 1
+fi
+
+echo "✅ Coverage priorities within acceptable range"
+```
+
+### Multiple Thresholds
+
+```bash
+#!/bin/bash
+# scripts/coverage-gate.sh
+
+CRITICAL_THRESHOLD=150
+WARNING_THRESHOLD=75
+
+TOP_SCORE=$(npx @redaksjon/brennpunkt --json --top 1 | jq '.files[0].priorityScore // 0')
+
+if (( $(echo "$TOP_SCORE > $CRITICAL_THRESHOLD" | bc -l) )); then
+  echo "❌ CRITICAL: Coverage gap too high (score: $TOP_SCORE > $CRITICAL_THRESHOLD)"
+  npx @redaksjon/brennpunkt --top 5
+  exit 1
+elif (( $(echo "$TOP_SCORE > $WARNING_THRESHOLD" | bc -l) )); then
+  echo "⚠️ WARNING: Coverage gap detected (score: $TOP_SCORE > $WARNING_THRESHOLD)"
+  npx @redaksjon/brennpunkt --top 5
+  # Don't fail, just warn
+fi
+
+echo "✅ Coverage priorities acceptable"
+```
+
+## Pre-Commit Hook
+
+Run brennpunkt before committing:
+
+```bash
+# .husky/pre-commit
+npm test -- --coverage
+npx @redaksjon/brennpunkt --top 5
+```
+
+## Scheduled Reports
+
+Generate weekly coverage priority reports:
+
+```yaml
+# .github/workflows/weekly-coverage.yml
+name: Weekly Coverage Report
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday at 9am
+
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - run: npm ci
+      - run: npm test -- --coverage
+      
+      - name: Generate Report
+        run: |
+          echo "# Weekly Coverage Priority Report" > report.md
+          echo "" >> report.md
+          echo "Generated: $(date)" >> report.md
+          echo "" >> report.md
+          echo '```' >> report.md
+          npx @redaksjon/brennpunkt --top 20 >> report.md
+          echo '```' >> report.md
+      
+      - name: Create Issue
+        uses: peter-evans/create-issue-from-file@v4
+        with:
+          title: Weekly Coverage Priority Report
+          content-filepath: report.md
+          labels: coverage,automated
+```
+
+## Makefile Integration
+
+```makefile
+.PHONY: test coverage priority
+
+test:
+	npm test -- --coverage
+
+coverage: test
+	npx @redaksjon/brennpunkt --top 10
+
+priority:
+	npx @redaksjon/brennpunkt --json > coverage-priority.json
+
+check: test
+	@./scripts/coverage-gate.sh
+```

package/guide/quickstart.md

@@ -0,0 +1,119 @@
+# Quick Start Guide
+
+Get brennpunkt working in 2 minutes.
+
+## Prerequisites
+
+- Node.js 20+
+- A project with lcov.info coverage output
+
+## Installation
+
+```bash
+npm install -g @redaksjon/brennpunkt
+```
+
+Or use directly with npx:
+
+```bash
+npx @redaksjon/brennpunkt
+```
+
+## First Analysis
+
+### 1. Generate Coverage
+
+Run your tests with coverage enabled:
+
+```bash
+# Vitest
+npm test -- --coverage
+
+# Jest  
+npm test -- --coverage
+
+# c8/NYC
+npx c8 npm test
+```
+
+### 2. Run Brennpunkt
+
+```bash
+# Auto-discovers coverage file
+brennpunkt
+
+# Or specify path explicitly
+brennpunkt coverage/lcov.info
+```
+
+### 3. View Results
+
+```
+📊 Coverage Priority Report
+
+┌─────────────────────────────────────────────────────────────────┐
+│                      OVERALL COVERAGE                           │
+├─────────────────┬─────────────────┬─────────────────────────────┤
+│  Lines: 85.20%  │  Functions: 90.00%  │  Branches: 72.50%       │
+└─────────────────┴─────────────────┴─────────────────────────────┘
+
+Priority  File                          Lines    Funcs    Branch   Score
+────────────────────────────────────────────────────────────────────────
+#1        src/auth/login.ts            45.2%    50.0%    35.0%    156.3
+#2        src/api/handler.ts           62.5%    70.0%    55.0%    98.7
+#3        src/utils/parser.ts          78.3%    85.0%    68.2%    67.2
+
+🎯 Recommended Focus (Top 3):
+  1. src/auth/login.ts - 13 untested branches, 5 untested functions
+```
+
+## Common Options
+
+```bash
+# Show only top 10 priority files
+brennpunkt --top 10
+
+# JSON output for automation
+brennpunkt --json
+
+# Custom weights (prioritize branch coverage)
+brennpunkt --weights 0.7,0.2,0.1
+
+# Exclude small files
+brennpunkt --min-lines 50
+
+# Verbose output
+brennpunkt --verbose
+```
+
+## Automatic Post-Test Analysis
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "test": "vitest run --coverage",
+    "posttest": "brennpunkt --top 10"
+  }
+}
+```
+
+Now every `npm test` automatically shows coverage priorities.
+
+## Create Configuration File
+
+```bash
+# Generate default config
+brennpunkt --init-config
+
+# View resolved config
+brennpunkt --check-config
+```
+
+## Next Steps
+
+- [Usage Reference](./usage.md): All CLI options
+- [Scoring](./scoring.md): Understand priority scores
+- [Integration](./integration.md): CI/CD setup
+- [Configuration](./configuration.md): Config file options