@redaksjon/brennpunkt 0.0.1

package/guide/api.md

@@ -0,0 +1,324 @@
+# Programmatic API
+
+Use brennpunkt as a library in your Node.js applications.
+
+## Installation
+
+```bash
+npm install @redaksjon/brennpunkt
+```
+
+## Basic Usage
+
+```typescript
+import { parseLcov, analyzeCoverage, formatJson, formatTable } from '@redaksjon/brennpunkt';
+import { readFileSync } from 'node:fs';
+
+// Read coverage file
+const lcovContent = readFileSync('coverage/lcov.info', 'utf-8');
+
+// Parse LCOV format
+const files = parseLcov(lcovContent);
+
+// Analyze with default weights
+const result = analyzeCoverage(
+  files,
+  { branches: 0.5, functions: 0.3, lines: 0.2 },  // weights
+  10,   // minLines
+  null  // top (null = all files)
+);
+
+// Output as JSON
+console.log(formatJson(result));
+
+// Or as formatted table
+console.log(formatTable(result, { 
+  coveragePath: 'coverage/lcov.info',
+  weights: { branches: 0.5, functions: 0.3, lines: 0.2 },
+  minLines: 10,
+  json: false,
+  top: null
+}));
+```
+
+## API Reference
+
+### `parseLcov(content: string): FileCoverage[]`
+
+Parse LCOV format content into structured coverage data.
+
+**Parameters**:
+- `content`: Raw LCOV file content as string
+
+**Returns**: Array of `FileCoverage` objects
+
+```typescript
+interface FileCoverage {
+  file: string;
+  linesFound: number;
+  linesHit: number;
+  functionsFound: number;
+  functionsHit: number;
+  branchesFound: number;
+  branchesHit: number;
+}
+```
+
+**Example**:
+
+```typescript
+const lcov = `SF:src/index.ts
+LF:100
+LH:80
+FNF:10
+FNH:8
+BRF:20
+BRH:15
+end_of_record`;
+
+const files = parseLcov(lcov);
+// [{ file: 'src/index.ts', linesFound: 100, linesHit: 80, ... }]
+```
+
+### `analyzeCoverage(files, weights, minLines, top): AnalysisResult`
+
+Analyze coverage data and calculate priority scores.
+
+**Parameters**:
+- `files`: Array of `FileCoverage` from `parseLcov()`
+- `weights`: `PriorityWeights` object
+- `minLines`: Minimum lines threshold (number)
+- `top`: Limit to top N files (number or null)
+
+```typescript
+interface PriorityWeights {
+  branches: number;
+  functions: number;
+  lines: number;
+}
+```
+
+**Returns**: `AnalysisResult` object
+
+```typescript
+interface AnalysisResult {
+  overall: {
+    lines: { found: number; hit: number; coverage: number };
+    functions: { found: number; hit: number; coverage: number };
+    branches: { found: number; hit: number; coverage: number };
+    fileCount: number;
+  };
+  files: AnalyzedFile[];
+}
+
+interface AnalyzedFile {
+  file: string;
+  lines: { found: number; hit: number; coverage: number };
+  functions: { found: number; hit: number; coverage: number };
+  branches: { found: number; hit: number; coverage: number };
+  priorityScore: number;
+  uncoveredLines: number;
+  uncoveredBranches: number;
+}
+```
+
+**Example**:
+
+```typescript
+const result = analyzeCoverage(
+  files,
+  { branches: 0.5, functions: 0.3, lines: 0.2 },
+  10,
+  5  // Top 5 only
+);
+
+console.log(result.overall.lines.coverage);  // 85.5
+console.log(result.files[0].priorityScore);  // 156.3
+```
+
+### `formatJson(result: AnalysisResult): string`
+
+Format analysis result as JSON string.
+
+**Parameters**:
+- `result`: `AnalysisResult` from `analyzeCoverage()`
+
+**Returns**: Formatted JSON string
+
+```typescript
+const jsonOutput = formatJson(result);
+console.log(jsonOutput);
+// { "overall": { ... }, "files": [ ... ] }
+```
+
+### `formatTable(result, options): string`
+
+Format analysis result as human-readable table.
+
+**Parameters**:
+- `result`: `AnalysisResult` from `analyzeCoverage()`
+- `options`: `AnalyzerOptions` object
+
+**Returns**: Formatted table string with ANSI colors
+
+```typescript
+interface AnalyzerOptions {
+  coveragePath: string;
+  weights: PriorityWeights;
+  minLines: number;
+  json: boolean;
+  top: number | null;
+}
+```
+
+### `discoverCoverageFile(): { found: string; searched: string[] } | null`
+
+Search for coverage file in common locations.
+
+**Returns**: Object with found path and searched paths, or null if not found
+
+```typescript
+const discovery = discoverCoverageFile();
+if (discovery) {
+  console.log(`Found: ${discovery.found}`);
+  console.log(`Searched: ${discovery.searched.join(', ')}`);
+} else {
+  console.log('No coverage file found');
+}
+```
+
+## Advanced Examples
+
+### Custom Analysis Pipeline
+
+```typescript
+import { parseLcov, analyzeCoverage } from '@redaksjon/brennpunkt';
+import { readFileSync, writeFileSync } from 'node:fs';
+
+async function runAnalysis() {
+  // Read coverage
+  const lcov = readFileSync('coverage/lcov.info', 'utf-8');
+  const files = parseLcov(lcov);
+  
+  // Filter specific directories
+  const srcFiles = files.filter(f => f.file.startsWith('src/'));
+  
+  // Analyze with custom weights
+  const result = analyzeCoverage(
+    srcFiles,
+    { branches: 0.7, functions: 0.2, lines: 0.1 },
+    20,
+    10
+  );
+  
+  // Process results
+  const criticalFiles = result.files.filter(f => f.priorityScore > 100);
+  
+  if (criticalFiles.length > 0) {
+    console.error('Critical coverage gaps:');
+    criticalFiles.forEach(f => {
+      console.error(`  - ${f.file}: ${f.priorityScore.toFixed(1)}`);
+    });
+    process.exit(1);
+  }
+  
+  // Save report
+  writeFileSync('coverage-analysis.json', JSON.stringify(result, null, 2));
+}
+
+runAnalysis();
+```
+
+### Integration with Test Framework
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    coverage: {
+      reporter: ['lcov', 'text'],
+    },
+    onFinished: async () => {
+      const { parseLcov, analyzeCoverage, formatTable } = await import('@redaksjon/brennpunkt');
+      const { readFileSync } = await import('node:fs');
+      
+      const lcov = readFileSync('coverage/lcov.info', 'utf-8');
+      const files = parseLcov(lcov);
+      const result = analyzeCoverage(
+        files,
+        { branches: 0.5, functions: 0.3, lines: 0.2 },
+        10,
+        5
+      );
+      
+      console.log('\n' + formatTable(result, {
+        coveragePath: 'coverage/lcov.info',
+        weights: { branches: 0.5, functions: 0.3, lines: 0.2 },
+        minLines: 10,
+        json: false,
+        top: 5
+      }));
+    }
+  }
+});
+```
+
+### AI/LLM Integration
+
+```typescript
+import { parseLcov, analyzeCoverage } from '@redaksjon/brennpunkt';
+import { readFileSync } from 'node:fs';
+
+// Get actionable data for AI assistants
+function getCoverageTargets(topN = 3) {
+  const lcov = readFileSync('coverage/lcov.info', 'utf-8');
+  const files = parseLcov(lcov);
+  const result = analyzeCoverage(
+    files,
+    { branches: 0.5, functions: 0.3, lines: 0.2 },
+    10,
+    topN
+  );
+  
+  return result.files.map(f => ({
+    file: f.file,
+    priority: f.priorityScore,
+    missingBranches: f.uncoveredBranches,
+    missingLines: f.uncoveredLines,
+    branchCoverage: f.branches.coverage,
+    suggestion: f.branches.coverage < 50 
+      ? 'Focus on branch coverage - test conditional logic'
+      : f.functions.coverage < 50
+        ? 'Focus on function coverage - test more entry points'
+        : 'General coverage improvement'
+  }));
+}
+
+// Example output for AI:
+// [
+//   {
+//     file: 'src/auth/login.ts',
+//     priority: 156.3,
+//     missingBranches: 13,
+//     missingLines: 45,
+//     branchCoverage: 35,
+//     suggestion: 'Focus on branch coverage - test conditional logic'
+//   }
+// ]
+```
+
+## TypeScript Types
+
+All types are exported from the package:
+
+```typescript
+import type {
+  FileCoverage,
+  AnalyzedFile,
+  AnalysisResult,
+  PriorityWeights,
+  AnalyzerOptions
+} from '@redaksjon/brennpunkt';
+```

package/guide/configuration.md

@@ -0,0 +1,235 @@
+# Configuration
+
+Brennpunkt can be configured via a YAML file in your project directory.
+
+## Configuration File
+
+Create a `brennpunkt.yaml` file in your project root:
+
+```yaml
+# Brennpunkt Configuration
+# https://github.com/redaksjon/brennpunkt
+
+# Path to lcov.info coverage file
+coveragePath: coverage/lcov.info
+
+# Priority weights for branches, functions, lines (should sum to 1.0)
+# Higher branch weight = untested branches are prioritized more heavily
+weights: "0.5,0.3,0.2"
+
+# Minimum number of lines for a file to be included
+# Helps filter out tiny utility files
+minLines: 10
+
+# Output format (true for JSON, false for table)
+json: false
+
+# Limit results to top N files (remove for all files)
+top: 20
+```
+
+## Generate Default Config
+
+Create a starter configuration file:
+
+```bash
+brennpunkt --init-config
+```
+
+This creates `brennpunkt.yaml` with all options commented out.
+
+## Custom Config Location
+
+Specify a different config file:
+
+```bash
+# Use config in .config directory
+brennpunkt --config .config/brennpunkt.yaml
+
+# Generate config at specific path
+brennpunkt --init-config --config .config/brennpunkt.yaml
+```
+
+## Configuration Options
+
+### `coveragePath`
+
+**Type**: `string`  
+**Default**: Auto-discovered
+
+Path to the lcov.info coverage file. If not specified, brennpunkt searches common locations.
+
+```yaml
+coveragePath: coverage/lcov.info
+```
+
+### `weights`
+
+**Type**: `string` (comma-separated numbers)  
+**Default**: `"0.5,0.3,0.2"`
+
+Priority weights for branches, functions, and lines. Should sum to 1.0.
+
+```yaml
+# Branch-heavy (for complex conditional logic)
+weights: "0.7,0.2,0.1"
+
+# Equal weights
+weights: "0.33,0.33,0.34"
+
+# Function-heavy (for finding dead code)
+weights: "0.2,0.6,0.2"
+```
+
+### `minLines`
+
+**Type**: `number`  
+**Default**: `10`
+
+Exclude files with fewer than this many lines. Helps filter noise from tiny files.
+
+```yaml
+# Default
+minLines: 10
+
+# More aggressive filtering
+minLines: 50
+
+# Include everything
+minLines: 0
+```
+
+### `json`
+
+**Type**: `boolean`  
+**Default**: `false`
+
+Output as JSON instead of formatted table.
+
+```yaml
+json: true
+```
+
+### `top`
+
+**Type**: `number`  
+**Default**: (all files)
+
+Limit output to top N priority files.
+
+```yaml
+top: 20
+```
+
+## Configuration Precedence
+
+Configuration is resolved in this order (highest priority first):
+
+1. **CLI arguments** - Always override everything
+2. **Config file** - `brennpunkt.yaml` in current directory
+3. **Built-in defaults** - Fallback values
+
+**Example**:
+
+```yaml
+# brennpunkt.yaml
+weights: "0.6,0.2,0.2"
+top: 20
+```
+
+```bash
+# CLI overrides config file
+brennpunkt --top 5
+# Uses: weights from config (0.6,0.2,0.2), top=5 from CLI
+```
+
+## Check Configuration
+
+View 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"
+  [config file] minLines       : 20
+  [default]     json           : false
+  [config file] top            : 10
+
+================================================================================
+```
+
+## Environment-Specific Configs
+
+For different environments, use the `--config` flag:
+
+```bash
+# Development (verbose)
+brennpunkt --config .config/brennpunkt.dev.yaml
+
+# CI (JSON output)
+brennpunkt --config .config/brennpunkt.ci.yaml
+```
+
+Example CI config:
+
+```yaml
+# .config/brennpunkt.ci.yaml
+json: true
+top: 10
+minLines: 20
+```
+
+## MCP Server Configuration
+
+The MCP server automatically loads each project's `brennpunkt.yaml`:
+
+- Pass `projectPath` as a parameter to each MCP tool call
+- The server reads `{projectPath}/brennpunkt.yaml` if it exists
+- Responses include `configUsed: "brennpunkt.yaml"` or `configUsed: "defaults"`
+- No per-project MCP server configuration needed
+
+This means different projects can have different analysis settings (weights, minLines, etc.) without any server reconfiguration.
+
+## Monorepo Usage
+
+For monorepos, place config files in each package:
+
+```
+packages/
+├── auth/
+│   ├── brennpunkt.yaml
+│   └── coverage/lcov.info
+├── api/
+│   ├── brennpunkt.yaml
+│   └── coverage/lcov.info
+└── shared/
+    ├── brennpunkt.yaml
+    └── coverage/lcov.info
+```
+
+Run from each package directory:
+
+```bash
+cd packages/auth && brennpunkt
+cd packages/api && brennpunkt
+```
+
+Or specify paths:
+
+```bash
+brennpunkt --config packages/auth/brennpunkt.yaml packages/auth/coverage/lcov.info
+```