@redaksjon/brennpunkt 0.0.1

package/guide/scoring.md

@@ -0,0 +1,172 @@
+# Priority Scoring
+
+How brennpunkt calculates priority scores to identify where testing efforts will have the biggest impact.
+
+## The Formula
+
+```
+priorityScore = (branchGap × branchWeight + functionGap × functionWeight + lineGap × lineWeight) × log₁₀(lines + 1)
+```
+
+Where:
+- `branchGap` = 100 - branch coverage percentage
+- `functionGap` = 100 - function coverage percentage
+- `lineGap` = 100 - line coverage percentage
+- `lines` = total lines of code in the file
+
+## Default Weights
+
+| Metric | Weight | Reason |
+|--------|--------|--------|
+| Branch Coverage | 0.5 (50%) | Untested branches hide conditional bugs |
+| Function Coverage | 0.3 (30%) | Untested functions indicate dead code or missing tests |
+| Line Coverage | 0.2 (20%) | Basic execution path; high coverage doesn't guarantee correctness |
+
+## Why These Weights?
+
+### Branch Coverage (50%)
+
+Branches are the most important because:
+- A function can execute but still have untested error paths
+- Untested `if/else` and `switch` cases often hide bugs
+- Edge cases and error handling live in branches
+
+**Example**: A login function might have 100% line coverage but 50% branch coverage because the "invalid password" path was never tested.
+
+### Function Coverage (30%)
+
+Untested functions indicate:
+- Dead code that should be removed
+- Missing feature tests
+- Code paths that aren't exercised
+
+### Line Coverage (20%)
+
+Line coverage is the baseline but:
+- High line coverage doesn't mean the code is correct
+- It only shows that lines executed, not that they work correctly
+- Often inflated by simple getter/setter tests
+
+## Size Scaling
+
+The `log₁₀(lines + 1)` factor means:
+- Larger files with low coverage rank higher
+- A 1000-line file at 50% coverage ranks higher than a 10-line file at 50%
+- The logarithmic scale prevents huge files from dominating
+
+**Example scaling**:
+| Lines | Multiplier |
+|-------|------------|
+| 10 | 1.04 |
+| 100 | 2.00 |
+| 500 | 2.70 |
+| 1000 | 3.00 |
+| 5000 | 3.70 |
+
+## Example Calculations
+
+### File A: Large file, low coverage
+
+```
+file: src/complex-module.ts
+lines: 500
+branchCoverage: 40%
+functionCoverage: 60%
+lineCoverage: 70%
+
+branchGap = 100 - 40 = 60
+functionGap = 100 - 60 = 40
+lineGap = 100 - 70 = 30
+
+weightedGap = (60 × 0.5) + (40 × 0.3) + (30 × 0.2)
+            = 30 + 12 + 6 = 48
+
+priorityScore = 48 × log₁₀(501)
+              = 48 × 2.70
+              = 129.6
+```
+
+### File B: Small file, very low coverage
+
+```
+file: src/tiny-util.ts
+lines: 20
+branchCoverage: 0%
+functionCoverage: 0%
+lineCoverage: 50%
+
+branchGap = 100
+functionGap = 100
+lineGap = 50
+
+weightedGap = (100 × 0.5) + (100 × 0.3) + (50 × 0.2)
+            = 50 + 30 + 10 = 90
+
+priorityScore = 90 × log₁₀(21)
+              = 90 × 1.32
+              = 118.8
+```
+
+Even though File B has worse coverage percentages, File A ranks higher because it's a larger file with more impact.
+
+## Customizing Weights
+
+### Prioritize Branch Coverage
+
+When you want to focus on conditional logic:
+
+```bash
+brennpunkt --weights 0.7,0.2,0.1
+```
+
+Good for:
+- Complex business logic
+- Error handling code
+- Authentication/authorization
+
+### Equal Weights
+
+When all coverage types matter equally:
+
+```bash
+brennpunkt --weights 0.33,0.33,0.34
+```
+
+Good for:
+- General code quality
+- Balanced improvement
+
+### Prioritize Function Coverage
+
+When you suspect dead code:
+
+```bash
+brennpunkt --weights 0.2,0.6,0.2
+```
+
+Good for:
+- Legacy codebases
+- Code cleanup projects
+- Finding unused features
+
+## Interpreting Scores
+
+| Score Range | Priority | Action |
+|-------------|----------|--------|
+| > 100 | Critical | Focus testing efforts here immediately |
+| 50-100 | High | Should be addressed in next sprint |
+| 20-50 | Medium | Add to tech debt backlog |
+| < 20 | Low | Acceptable for now |
+
+## Score = 0
+
+A score of 0 means:
+- 100% coverage on all metrics, OR
+- File excluded by `--min-lines` filter
+
+## Files Not Scored
+
+Files are excluded from scoring if:
+- They have fewer lines than `--min-lines` threshold
+- They have no coverage data (not instrumented)
+- They're test files or config files (depending on your coverage setup)

package/guide/usage.md

@@ -0,0 +1,249 @@
+# Usage Reference
+
+Complete CLI reference for brennpunkt.
+
+## Basic Syntax
+
+```bash
+brennpunkt [coverage-path] [options]
+```
+
+## Arguments
+
+### `[coverage-path]`
+
+Path to the lcov.info file. Optional - if not provided, brennpunkt auto-discovers the file.
+
+**Auto-discovery locations** (searched in order):
+
+1. `coverage/lcov.info` - Jest, Vitest, c8
+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
+
+## Options
+
+### `-w, --weights <weights>`
+
+Custom weights for branches, functions, and lines coverage. Must be three comma-separated numbers.
+
+```bash
+# Default: branches=0.5, functions=0.3, lines=0.2
+brennpunkt --weights 0.5,0.3,0.2
+
+# Prioritize branch coverage heavily
+brennpunkt --weights 0.7,0.2,0.1
+
+# Equal weights
+brennpunkt --weights 0.33,0.33,0.34
+
+# Focus on function coverage
+brennpunkt --weights 0.2,0.6,0.2
+```
+
+### `-m, --min-lines <number>`
+
+Exclude files with fewer than N lines. Helps filter out tiny utility files.
+
+```bash
+# Default: 10 lines
+brennpunkt --min-lines 10
+
+# Only analyze files with 50+ lines
+brennpunkt --min-lines 50
+
+# Include all files (even 1-line files)
+brennpunkt --min-lines 0
+```
+
+### `-t, --top <number>`
+
+Show only the top N priority files.
+
+```bash
+# Show top 10
+brennpunkt --top 10
+
+# Show top 3
+brennpunkt --top 3
+
+# Show all files (default)
+brennpunkt
+```
+
+### `-j, --json`
+
+Output results as JSON instead of a formatted table.
+
+```bash
+# JSON output
+brennpunkt --json
+
+# JSON with top 5
+brennpunkt --json --top 5
+
+# Save to file
+brennpunkt --json > coverage-priority.json
+
+# Pipe to jq
+brennpunkt --json | jq '.files[0].file'
+```
+
+### `-c, --config <path>`
+
+Specify a custom configuration file path.
+
+```bash
+# Use specific config
+brennpunkt --config .config/brennpunkt.yaml
+
+# Use config in different location
+brennpunkt --config ~/brennpunkt-global.yaml
+```
+
+### `--init-config`
+
+Generate a default `brennpunkt.yaml` configuration file.
+
+```bash
+# Create in current directory
+brennpunkt --init-config
+
+# Create at specific path
+brennpunkt --init-config --config .config/brennpunkt.yaml
+```
+
+### `--check-config`
+
+Display the resolved configuration with source tracking.
+
+```bash
+brennpunkt --check-config
+```
+
+Output:
+
+```
+================================================================================
+BRENNPUNKT CONFIGURATION
+================================================================================
+
+Config file: brennpunkt.yaml
+Status: Found
+
+RESOLVED CONFIGURATION:
+--------------------------------------------------------------------------------
+  [config file] coveragePath   : "coverage/lcov.info"
+  [config file] weights        : "0.6,0.2,0.2"
+  [default]     minLines       : 10
+  [default]     json           : false
+  [config file] top            : 20
+
+================================================================================
+```
+
+### `-V, --version`
+
+Show version number.
+
+### `-h, --help`
+
+Show help message.
+
+## Examples
+
+### Basic Usage
+
+```bash
+# Analyze current project
+brennpunkt
+
+# Analyze specific file
+brennpunkt path/to/lcov.info
+
+# Show top priorities
+brennpunkt --top 10
+```
+
+### CI/CD Usage
+
+```bash
+# GitHub Actions / CI pipeline
+npx @redaksjon/brennpunkt --top 10
+
+# Save JSON artifact
+npx @redaksjon/brennpunkt --json > coverage-priority.json
+```
+
+### Automation
+
+```bash
+# Get top priority file
+TOP_FILE=$(brennpunkt --json --top 1 | jq -r '.files[0].file')
+echo "Focus on: $TOP_FILE"
+
+# Check if any file has score > 100
+brennpunkt --json | jq '.files[] | select(.priorityScore > 100)'
+
+# Fail if highest priority score is too high
+SCORE=$(brennpunkt --json --top 1 | jq '.files[0].priorityScore')
+if (( $(echo "$SCORE > 150" | bc -l) )); then
+  echo "Critical coverage gap detected!"
+  exit 1
+fi
+```
+
+### Combining Options
+
+```bash
+# Full analysis with custom weights, filtered
+brennpunkt --weights 0.6,0.2,0.2 --min-lines 50 --top 20
+
+# JSON output for top priorities
+brennpunkt --json --top 5 --min-lines 20
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error (file not found, invalid arguments, etc.) |
+
+## Output Formats
+
+### Table Output (Default)
+
+Human-readable formatted table with:
+- Overall coverage summary
+- Per-file coverage metrics
+- Priority scores
+- Recommended focus areas
+
+### JSON Output
+
+Machine-readable format:
+
+```json
+{
+  "overall": {
+    "lines": { "found": 1572, "hit": 1234, "coverage": 78.5 },
+    "functions": { "found": 190, "hit": 156, "coverage": 82.1 },
+    "branches": { "found": 150, "hit": 98, "coverage": 65.3 },
+    "fileCount": 25
+  },
+  "files": [
+    {
+      "file": "src/auth/login.ts",
+      "lines": { "found": 218, "hit": 98, "coverage": 45.0 },
+      "functions": { "found": 10, "hit": 5, "coverage": 50.0 },
+      "branches": { "found": 20, "hit": 7, "coverage": 35.0 },
+      "priorityScore": 156.32,
+      "uncoveredLines": 120,
+      "uncoveredBranches": 13
+    }
+  ]
+}
+```

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@redaksjon/brennpunkt",
+  "version": "0.0.1",
+  "description": "Coverage priority analyzer - identify where to focus testing efforts",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "brennpunkt": "./dist/main.js",
+    "brennpunkt-mcp": "./dist/mcp/server.js"
+  },
+  "files": [
+    "dist",
+    "guide",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./mcp": "./dist/mcp/server.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/redaksjon/brennpunkt.git"
+  },
+  "homepage": "https://github.com/redaksjon/brennpunkt",
+  "scripts": {
+    "build": "npm run lint && tsc --noEmit && vite build && chmod +x dist/main.js dist/mcp/server.js",
+    "dev": "vite",
+    "watch": "vite build --watch",
+    "test": "vitest run --coverage",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "precommit": "npm run lint && npm run test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "coverage",
+    "testing",
+    "lcov",
+    "analysis",
+    "priority",
+    "mcp",
+    "ai",
+    "cursor",
+    "claude",
+    "agentic"
+  ],
+  "author": "Tim O'Brien <tobrien@discursive.com>",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "commander": "^14.0.2",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.39.1",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@swc/core": "^1.15.1",
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^8.46.4",
+    "@typescript-eslint/parser": "^8.46.4",
+    "@vitest/coverage-v8": "^4.0.8",
+    "eslint": "^9.39.1",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^17.0.0",
+    "rollup-plugin-preserve-shebang": "^1.0.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.2",
+    "vite-plugin-node": "^7.0.0",
+    "vitest": "^4.0.8"
+  }
+}