@aprimediet/codewalker 1.2.0 → 1.4.0

package/src/analyze/coverage.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect } from 'vitest';
+import { parseLcov, parseCoverageJson, coverageSeverity } from './coverage.ts';
+
+describe('parseLcov', () => {
+  it('parses a simple lcov record with SF, DA, LF, LH', () => {
+    const input = `SF:src/auth/token.ts
+DA:1,1
+DA:2,1
+DA:3,0
+DA:4,1
+LF:4
+LH:3
+end_of_record`;
+    const results = parseLcov(input);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.file).toContain('src/auth/token.ts');
+    expect(results[0]!.lines_total).toBe(4);
+    expect(results[0]!.lines_covered).toBe(3);
+    expect(results[0]!.pct).toBeCloseTo(75, 1);
+  });
+
+  it('parses multiple records', () => {
+    const input = `SF:src/a.ts
+DA:1,1
+LF:1
+LH:1
+end_of_record
+SF:src/b.ts
+DA:1,0
+LF:1
+LH:0
+end_of_record`;
+    const results = parseLcov(input);
+    expect(results).toHaveLength(2);
+    expect(results[0]!.pct).toBe(100);
+    expect(results[1]!.pct).toBe(0);
+  });
+
+  it('handles empty input gracefully', () => {
+    const results = parseLcov('');
+    expect(results).toEqual([]);
+  });
+
+  it('handles malformed input without throwing', () => {
+    const results = parseLcov('not even close to lcov format');
+    expect(results).toEqual([]);
+  });
+
+  it('handles records with 0 total lines', () => {
+    const input = `SF:src/empty.ts
+DA:1,1
+LF:0
+LH:0
+end_of_record`;
+    const results = parseLcov(input);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.pct).toBe(100); // no lines = implicitly 100%
+  });
+
+  it('skips records with empty SF (no file path)', () => {
+    const input = `SF:
+DA:1,0
+LF:1
+LH:0
+end_of_record`;
+    const results = parseLcov(input);
+    expect(results).toHaveLength(0);
+  });
+});
+
+describe('parseCoverageJson', () => {
+  it('parses a coverage-final.json with per-file data', () => {
+    const input = {
+      'src/auth/token.ts': {
+        path: 'src/auth/token.ts',
+        statementMap: {},
+        fnMap: {},
+        branchMap: {},
+        s: { '0': 1, '1': 1, '2': 0 },
+        f: {},
+        b: {},
+      },
+    };
+    const results = parseCoverageJson(input);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.file).toContain('src/auth/token.ts');
+    expect(results[0]!.lines_total).toBe(3);
+    expect(results[0]!.lines_covered).toBe(2);
+  });
+
+  it('handles empty input', () => {
+    const results = parseCoverageJson({});
+    expect(results).toEqual([]);
+  });
+
+  it('handles null/undefined input gracefully', () => {
+    const results = parseCoverageJson(null as any);
+    expect(results).toEqual([]);
+    const results2 = parseCoverageJson(undefined as any);
+    expect(results2).toEqual([]);
+  });
+
+  it('handles files with no statements', () => {
+    const input = {
+      'src/empty.ts': {
+        path: 'src/empty.ts',
+        statementMap: {},
+        fnMap: {},
+        branchMap: {},
+        s: {},
+        f: {},
+        b: {},
+      },
+    };
+    const results = parseCoverageJson(input);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.pct).toBe(100);
+  });
+
+  it('calculates percentage correctly', () => {
+    const input = {
+      'src/test.ts': {
+        path: 'src/test.ts',
+        statementMap: { '0': { start: { line: 1, column: 0 }, end: { line: 1, column: 1 } } },
+        fnMap: {},
+        branchMap: {},
+        s: { '0': 0 },
+        f: {},
+        b: {},
+      },
+    };
+    const results = parseCoverageJson(input);
+    expect(results).toHaveLength(1);
+    expect(results[0]!.pct).toBe(0);
+    expect(results[0]!.lines_total).toBe(1);
+    expect(results[0]!.lines_covered).toBe(0);
+  });
+});
+
+describe('coverageSeverity', () => {
+  it('returns "high" for <50%', () => {
+    expect(coverageSeverity(0)).toBe('high');
+    expect(coverageSeverity(25)).toBe('high');
+    expect(coverageSeverity(49.9)).toBe('high');
+  });
+
+  it('returns "warn" for 50-80%', () => {
+    expect(coverageSeverity(50)).toBe('warn');
+    expect(coverageSeverity(65)).toBe('warn');
+    expect(coverageSeverity(79.9)).toBe('warn');
+  });
+
+  it('returns "info" for >=80%', () => {
+    expect(coverageSeverity(80)).toBe('info');
+    expect(coverageSeverity(95)).toBe('info');
+    expect(coverageSeverity(100)).toBe('info');
+  });
+});

package/src/analyze/coverage.ts

@@ -0,0 +1,98 @@
+/**
+ * Coverage data parser for codewalker v1.4.
+ *
+ * PURE module — no I/O. Parses lcov.info and coverage-final.json artifacts
+ * that already exist on disk. Never runs a coverage tool.
+ */
+
+import type { FileCoverage } from "../types.ts";
+
+/**
+ * Parse an lcov.info string into per-file coverage data.
+ * Supports SF:, DA:, LF:, LH: and end_of_record markers.
+ */
+export function parseLcov(text: string): FileCoverage[] {
+  if (!text.trim()) return [];
+
+  const results: FileCoverage[] = [];
+  let current: Record<string, any> | null = null;
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    if (trimmed.startsWith("SF:")) {
+      // Start a new record
+      current = { file: trimmed.slice(3).trim(), lines: [], lf: 0, lh: 0 };
+    } else if (current) {
+      if (trimmed.startsWith("DA:")) {
+        const parts = trimmed.slice(3).split(",");
+        const lineNo = parseInt(parts[0] ?? "0", 10);
+        const hit = parseInt(parts[1] ?? "0", 10);
+        if (!isNaN(lineNo)) {
+          current.lines.push({ line: lineNo, hit });
+        }
+      } else if (trimmed.startsWith("LF:")) {
+        current.lf = parseInt(trimmed.slice(3).trim(), 10);
+      } else if (trimmed.startsWith("LH:")) {
+        current.lh = parseInt(trimmed.slice(3).trim(), 10);
+      } else if (trimmed === "end_of_record") {
+        if (current.file) {
+          const total = current.lf || current.lines.length;
+          const covered = current.lh || current.lines.filter((l: any) => l.hit > 0).length;
+          const pct = total > 0 ? (covered / total) * 100 : 100;
+          results.push({
+            file: current.file,
+            lines_total: total,
+            lines_covered: covered,
+            pct: Math.round(pct * 10) / 10,
+          });
+        }
+        current = null;
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Parse a coverage-final.json object (istanbul/nyc format) into per-file coverage data.
+ */
+export function parseCoverageJson(
+  data: Record<string, any> | null | undefined,
+): FileCoverage[] {
+  if (!data || typeof data !== "object") return [];
+
+  const results: FileCoverage[] = [];
+
+  for (const [filePath, fileData] of Object.entries(data)) {
+    if (!fileData || typeof fileData !== "object") continue;
+    const s = (fileData as any).s;
+    if (!s || typeof s !== "object") continue;
+
+    const statements = Object.values(s) as number[];
+    const total = statements.length;
+    const covered = statements.filter((v) => v > 0).length;
+    const pct = total > 0 ? (covered / total) * 100 : 100;
+
+    results.push({
+      file: filePath,
+      lines_total: total,
+      lines_covered: covered,
+      pct: Math.round(pct * 10) / 10,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Map a coverage percentage to a severity level.
+ * <50% → high, 50-80% → warn, >=80% → info.
+ */
+export function coverageSeverity(pct: number): "info" | "warn" | "high" {
+  if (pct < 50) return "high";
+  if (pct < 80) return "warn";
+  return "info";
+}

package/src/analyze/debt.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { scanDebt, LARGE_FILE_LINES, LONG_FN_LINES } from './debt.ts';
+import type { DebtFinding } from './debt.ts';
+
+describe('scanDebt', () => {
+  it('finds TODO markers with correct line numbers', () => {
+    const content = `// normal line
+const x = 1;
+// TODO: fix this
+function y() {} // TODO: refactor later
+`;
+    const findings = scanDebt('src/a.ts', content, []);
+    const todos = findings.filter(f => f.marker === 'TODO');
+    expect(todos).toHaveLength(2);
+    expect(todos[0]!.line_start).toBe(3);
+    expect(todos[1]!.line_start).toBe(4);
+  });
+
+  it('finds FIXME markers', () => {
+    const content = `// FIXME: this is broken
+const x = 1;
+`;
+    const findings = scanDebt('src/a.ts', content, []);
+    const fixmes = findings.filter(f => f.marker === 'FIXME');
+    expect(fixmes).toHaveLength(1);
+    expect(fixmes[0]!.line_start).toBe(1);
+  });
+
+  it('finds HACK markers', () => {
+    const content = `// HACK: workaround for edge case
+const x = 1;
+`;
+    const findings = scanDebt('src/a.ts', content, []);
+    const hacks = findings.filter(f => f.marker === 'HACK');
+    expect(hacks).toHaveLength(1);
+  });
+
+  it('finds XXX markers', () => {
+    const content = `// XXX: this needs attention
+const x = 1;
+`;
+    const findings = scanDebt('src/a.ts', content, []);
+    const xxxs = findings.filter(f => f.marker === 'XXX');
+    expect(xxxs).toHaveLength(1);
+  });
+
+  it('counts @ts-ignore occurrences', () => {
+    const content = `// @ts-ignore
+const x: any = 1;
+// @ts-ignore — next line
+const y: any = 2;
+`;
+    const findings = scanDebt('src/a.ts', content, []);
+    const tsIgnores = findings.filter(f => f.marker === '@ts-ignore');
+    expect(tsIgnores).toHaveLength(2);
+  });
+
+  it('counts @ts-nocheck occurrences', () => {
+    const content = `// @ts-nocheck
+const x = 1;
+`;
+    const findings = scanDebt('src/a.ts', content, []);
+    const tsNocheck = findings.filter(f => f.marker === '@ts-nocheck');
+    expect(tsNocheck).toHaveLength(1);
+  });
+
+  it('flags a file as oversized when lines exceed LARGE_FILE_LINES', () => {
+    const content = Array.from({ length: LARGE_FILE_LINES + 50 }, (_, i) =>
+      `line ${i + 1}`
+    ).join('\n');
+    const findings = scanDebt('src/large.ts', content, []);
+    const oversize = findings.filter(f => f.marker === 'oversized-file');
+    expect(oversize).toHaveLength(1);
+    expect(oversize[0]!.severity).toBe('warn');
+    expect(oversize[0]!.metric).toContain(String(LARGE_FILE_LINES + 50));
+  });
+
+  it('does NOT flag a file under the limit', () => {
+    const content = Array.from({ length: 10 }, (_, i) => `line ${i + 1}`).join('\n');
+    const findings = scanDebt('src/small.ts', content, []);
+    const oversize = findings.filter(f => f.marker === 'oversized-file');
+    expect(oversize).toHaveLength(0);
+  });
+
+  it('flags functions longer than LONG_FN_LINES using existing symbol spans', () => {
+    const symbols = [
+      { name: 'longFunc', kind: 'function', file_path: 'src/big.ts', line_start: 1, line_end: LONG_FN_LINES + 50 },
+      { name: 'shortFunc', kind: 'function', file_path: 'src/big.ts', line_start: 200, line_end: 210 },
+    ];
+    const content = '';
+    const findings = scanDebt('src/big.ts', content, symbols);
+    const longFn = findings.filter(f => f.marker === 'long-function');
+    expect(longFn).toHaveLength(1);
+    expect(longFn[0]!.title).toContain('longFunc');
+    expect(longFn[0]!.severity).toBe('warn');
+  });
+
+  it('returns empty array for clean file', () => {
+    const content = `const x = 1;
+const y = 2;
+function foo() { return x + y; }
+`;
+    const findings = scanDebt('src/clean.ts', content, []);
+    expect(findings).toHaveLength(0);
+  });
+
+  it('handles empty content', () => {
+    const findings = scanDebt('src/empty.ts', '', []);
+    expect(findings).toEqual([]);
+  });
+});

package/src/analyze/debt.ts

@@ -0,0 +1,180 @@
+/**
+ * Technical debt scanner for codewalker v1.4.
+ *
+ * PURE module — no I/O. Scans source file content for:
+ * - TODO/FIXME/HACK/XXX markers
+ * - @ts-ignore / @ts-nocheck usage
+ * - Oversized files (>400 lines)
+ * - Long functions (>120 lines, derived from existing symbol rows)
+ */
+
+/** Default threshold for oversized file warning (lines). */
+export const LARGE_FILE_LINES = 400;
+
+/** Default threshold for long function warning (lines). */
+export const LONG_FN_LINES = 120;
+
+/** A single debt finding. */
+export interface DebtFinding {
+  title: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+  marker: string;
+  severity: "info" | "warn" | "high";
+  metric: string;
+  body: string;
+}
+
+/** A symbol row passed for function-length analysis. */
+interface SymbolSpan {
+  name: string;
+  kind: string;
+  file_path: string;
+  line_start: number;
+  line_end: number;
+}
+
+// Word-boundary regex for each marker type.
+const MARKER_RE = /\b(TODO|FIXME|HACK|XXX)\b(?:\s*[:-]?\s*(.*))?/g;
+const TS_IGNORE_RE = /\/\/\s*@ts-ignore\b/g;
+const TS_NOCHECK_RE = /\/\/\s*@ts-nocheck\b/g;
+
+/**
+ * Scan a file's content for debt markers and heuristics.
+ *
+ * @param filePath - Absolute or relative file path (for the finding).
+ * @param content - The full file content string.
+ * @param symbols - Existing symbol rows for this file (for function-length analysis).
+ * @returns An array of debt findings.
+ */
+export function scanDebt(
+  filePath: string,
+  content: string,
+  symbols: SymbolSpan[],
+): DebtFinding[] {
+  const findings: DebtFinding[] = [];
+  const lines = content ? content.split("\n") : [];
+
+  // --- Scan markers in content ---
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+
+    // TODO/FIXME/HACK/XXX
+    MARKER_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = MARKER_RE.exec(line)) !== null) {
+      const marker = m[1]!;
+      const detail = (m[2] ?? "").trim();
+      const severity = marker === "FIXME" || marker === "HACK" ? "warn" : "info";
+      findings.push({
+        title: `${marker}: ${detail || line.trim().slice(0, 50)}`,
+        file_path: filePath,
+        line_start: i + 1,
+        line_end: i + 1,
+        marker,
+        severity,
+        metric: marker,
+        body: line.trim(),
+      });
+    }
+
+    // @ts-ignore
+    TS_IGNORE_RE.lastIndex = 0;
+    if (TS_IGNORE_RE.test(line)) {
+      findings.push({
+        title: `@ts-ignore at line ${i + 1}`,
+        file_path: filePath,
+        line_start: i + 1,
+        line_end: i + 1,
+        marker: "@ts-ignore",
+        severity: "warn",
+        metric: "@ts-ignore",
+        body: line.trim(),
+      });
+    }
+
+    // @ts-nocheck
+    TS_NOCHECK_RE.lastIndex = 0;
+    if (TS_NOCHECK_RE.test(line)) {
+      findings.push({
+        title: `@ts-nocheck in ${filePath}`,
+        file_path: filePath,
+        line_start: i + 1,
+        line_end: i + 1,
+        marker: "@ts-nocheck",
+        severity: "high",
+        metric: "@ts-nocheck",
+        body: line.trim(),
+      });
+    }
+  }
+
+  // --- Oversized file heuristic ---
+  if (lines.length > LARGE_FILE_LINES) {
+    findings.push({
+      title: `Oversized file: ${lines.length} lines`,
+      file_path: filePath,
+      line_start: 0,
+      line_end: lines.length,
+      marker: "oversized-file",
+      severity: "warn",
+      metric: `${lines.length} lines`,
+      body: `File has ${lines.length} lines, exceeding the ${LARGE_FILE_LINES}-line threshold. Consider splitting into smaller modules.`,
+    });
+  }
+
+  // --- Long function heuristic (from existing symbols) ---
+  for (const sym of symbols) {
+    if (sym.file_path !== filePath) continue;
+    const fnLength = sym.line_end - sym.line_start;
+    if (fnLength > LONG_FN_LINES) {
+      findings.push({
+        title: `Long function: ${sym.name} (${fnLength} lines)`,
+        file_path: filePath,
+        line_start: sym.line_start,
+        line_end: sym.line_end,
+        marker: "long-function",
+        severity: "warn",
+        metric: `fn length ${fnLength}`,
+        body: `Function "${sym.name}" spans ${fnLength} lines (limit: ${LONG_FN_LINES}). Consider refactoring.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Group and summarize debt findings for a file.
+ * Returns at most one finding per marker type with aggregated counts.
+ */
+export function summarizeDebt(findings: DebtFinding[]): DebtFinding[] {
+  if (findings.length === 0) return [];
+
+  const groups = new Map<string, DebtFinding[]>();
+  for (const f of findings) {
+    const key = f.marker;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key)!.push(f);
+  }
+
+  const result: DebtFinding[] = [];
+  for (const [, group] of groups) {
+    const first = group[0]!;
+    if (group.length === 1) {
+      result.push(first);
+    } else {
+      result.push({
+        ...first,
+        title: `${first.marker}: ${group.length} occurrences`,
+        metric: `${first.marker} x${group.length}`,
+        body: group.map(f => `  line ${f.line_start}: ${f.body}`).join("\n"),
+        line_start: group[0]!.line_start,
+        line_end: group[group.length - 1]!.line_end,
+      });
+    }
+  }
+
+  return result;
+}

package/src/analyze/review.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validateReviewPath,
+  checkReviewCap,
+  selectFilesForReview,
+  formatReviewWorklist,
+  DEFAULT_REVIEW_CAP,
+} from './review.ts';
+
+describe('validateReviewPath', () => {
+  it('accepts a non-empty path', () => {
+    const result = validateReviewPath('src/auth');
+    expect(result.valid).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('rejects empty string', () => {
+    const result = validateReviewPath('');
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('Specify a path');
+  });
+
+  it('rejects whitespace-only', () => {
+    const result = validateReviewPath('   ');
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('Specify a path');
+  });
+
+  it('rejects undefined/null', () => {
+    const result = validateReviewPath(undefined as any);
+    expect(result.valid).toBe(false);
+    expect(result.error).toContain('Specify a path');
+  });
+});
+
+describe('checkReviewCap', () => {
+  it('returns ok when count within cap', () => {
+    const result = checkReviewCap(5, 25);
+    expect(result.ok).toBe(true);
+    expect(result.count).toBe(5);
+    expect(result.skipped).toBe(0);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('rejects when count exceeds cap', () => {
+    const result = checkReviewCap(100, 25);
+    expect(result.ok).toBe(false);
+    expect(result.count).toBe(100);
+    expect(result.skipped).toBe(75);
+    expect(result.error).toContain('Narrow your path');
+  });
+
+  it('uses default cap when not specified', () => {
+    const result = checkReviewCap(50);
+    expect(result.ok).toBe(false);
+    expect(result.error).toContain('--max');
+  });
+
+  it('accepts edge case at exactly cap', () => {
+    const result = checkReviewCap(25, 25);
+    expect(result.ok).toBe(true);
+    expect(result.count).toBe(25);
+  });
+});
+
+describe('selectFilesForReview', () => {
+  const files = [
+    'src/auth/token.ts',
+    'src/auth/session.ts',
+    'src/api/route.ts',
+    'src/api/handler.ts',
+    'src/db/query.ts',
+  ];
+
+  it('selects files under a path prefix', () => {
+    const result = selectFilesForReview(files, 'src/auth', 25);
+    expect(result).toHaveLength(2);
+    expect(result).toContain('src/auth/token.ts');
+    expect(result).toContain('src/auth/session.ts');
+  });
+
+  it('respects the cap', () => {
+    const result = selectFilesForReview(files, 'src/', 3);
+    expect(result).toHaveLength(3);
+  });
+
+  it('returns empty array for non-matching prefix', () => {
+    const result = selectFilesForReview(files, 'src/nonexistent', 25);
+    expect(result).toEqual([]);
+  });
+
+  it('returns all matching files when under cap', () => {
+    const result = selectFilesForReview(files, 'src/api', 25);
+    expect(result).toHaveLength(2);
+  });
+
+  it('returns exact cap when match count equals cap', () => {
+    const result = selectFilesForReview(files, '', 5);
+    expect(result).toHaveLength(5);
+  });
+});
+
+describe('formatReviewWorklist', () => {
+  it('formats a worklist with file list and instructions', () => {
+    const files = ['src/auth/token.ts', 'src/auth/session.ts'];
+    const result = formatReviewWorklist(files, 'src/auth');
+    expect(result).toContain('2 file(s) under');
+    expect(result).toContain('src/auth');
+    expect(result).toContain('src/auth/token.ts');
+    expect(result).toContain('src/auth/session.ts');
+    expect(result).toContain('codewalker_finding');
+    expect(result).toContain('conventions');
+    expect(result).toContain('decisions');
+  });
+
+  it('handles empty file list', () => {
+    const result = formatReviewWorklist([], 'src/auth');
+    expect(result).toContain('No files found');
+  });
+
+  it('includes the max files info when files hit the cap', () => {
+    const files = Array.from({ length: 25 }, (_, i) => `src/a${i}.ts`);
+    const result = formatReviewWorklist(files, 'src/');
+    expect(result).toContain('25');
+    expect(result).toContain('selected for review');
+  });
+});