@aprimediet/codewalker 1.3.0 → 1.4.0

package/src/analyze/cards.test.ts

@@ -0,0 +1,156 @@
+import { describe, it, expect } from 'vitest';
+import { renderAnalysisCard, parseAnalysisCard } from './cards.ts';
+
+describe('renderAnalysisCard', () => {
+  it('renders a coverage finding as markdown with frontmatter', () => {
+    const finding = {
+      finding_kind: 'coverage' as const,
+      title: 'Low coverage: src/auth/token.ts',
+      severity: 'warn' as const,
+      file_path: 'src/auth/token.ts',
+      line_start: 0,
+      line_end: 0,
+      metric: '38% (24/63 lines)',
+      body: 'Auth token refresh path is under-tested — 38% line coverage.',
+      related: 'refreshToken, token.ts:42-71',
+      card_path: '',
+    };
+    const card = renderAnalysisCard(finding);
+    expect(card).toContain('---');
+    expect(card).toContain('finding_kind: coverage');
+    expect(card).toContain('title: Low coverage: src/auth/token.ts');
+    expect(card).toContain('severity: warn');
+    expect(card).toContain('location: src/auth/token.ts');
+    expect(card).toContain('metric: 38% (24/63 lines)');
+    expect(card).toContain('summary: Auth token refresh path is under-tested');
+    expect(card).toContain('# Low coverage: src/auth/token.ts');
+    expect(card).toContain('38% line coverage.');
+  });
+
+  it('renders a debt finding with correct fields', () => {
+    const finding = {
+      finding_kind: 'debt' as const,
+      title: 'TODO: fix this',
+      severity: 'info' as const,
+      file_path: 'src/auth/handler.ts',
+      line_start: 42,
+      line_end: 42,
+      metric: 'TODO',
+      body: 'Need to handle edge case',
+      related: '',
+      card_path: '',
+    };
+    const card = renderAnalysisCard(finding);
+    expect(card).toContain('finding_kind: debt');
+    expect(card).toContain('TODO: fix this');
+    expect(card).toContain('location: src/auth/handler.ts:42');
+    expect(card).toContain('metric: TODO');
+  });
+
+  it('renders a practice finding', () => {
+    const finding = {
+      finding_kind: 'practice' as const,
+      title: 'Missing error handling',
+      severity: 'high' as const,
+      file_path: 'src/api/route.ts',
+      line_start: 15,
+      line_end: 15,
+      metric: '',
+      body: 'This function does not handle rejected promises.',
+      related: 'handleRequest, src/api/route.ts:10-30',
+      card_path: '',
+    };
+    const card = renderAnalysisCard(finding);
+    expect(card).toContain('finding_kind: practice');
+    expect(card).toContain('severity: high');
+    expect(card).toContain('handleRequest');
+  });
+
+  it('sanitizes newlines in frontmatter fields', () => {
+    const finding = {
+      finding_kind: 'debt' as const,
+      title: 'TODO: fix this\nand that',
+      severity: 'info' as const,
+      file_path: 'src/a.ts',
+      line_start: 1,
+      line_end: 1,
+      metric: 'TODO',
+      body: 'Multi\nline\nbody',
+      related: 'sym1\nsym2',
+      card_path: '',
+    };
+    const card = renderAnalysisCard(finding);
+    // Frontmatter should not contain literal newlines
+    const frontmatter = card.split('---')[1] ?? '';
+    expect(frontmatter).not.toContain('\n  '); // no indented continuation lines
+    // Title in frontmatter should be flattened
+    expect(frontmatter).toContain('fix this and that');
+  });
+
+  it('uses body first line as summary when body has no explicit summary field', () => {
+    const finding = {
+      finding_kind: 'coverage' as const,
+      title: 'Test',
+      severity: 'info' as const,
+      file_path: 'src/a.ts',
+      line_start: 0,
+      line_end: 0,
+      metric: '',
+      body: 'First line is the summary.\nSecond line.',
+      related: '',
+      card_path: '',
+    };
+    const card = renderAnalysisCard(finding);
+    expect(card).toContain('summary: First line is the summary.');
+  });
+});
+
+describe('parseAnalysisCard', () => {
+  it('parses a card rendered by renderAnalysisCard', () => {
+    const finding = {
+      finding_kind: 'coverage' as const,
+      title: 'Low coverage: src/auth/token.ts',
+      severity: 'warn' as const,
+      file_path: 'src/auth/token.ts',
+      line_start: 0,
+      line_end: 0,
+      metric: '38% (24/63 lines)',
+      body: 'Auth token refresh path is under-tested.',
+      related: 'refreshToken',
+      card_path: '',
+    };
+    const card = renderAnalysisCard(finding);
+    const parsed = parseAnalysisCard(card);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.finding_kind).toBe('coverage');
+    expect(parsed!.title).toBe('Low coverage: src/auth/token.ts');
+    expect(parsed!.severity).toBe('warn');
+    expect(parsed!.location).toBe('src/auth/token.ts');
+    expect(parsed!.metric).toBe('38% (24/63 lines)');
+    expect(parsed!.summary).toBe('Auth token refresh path is under-tested.');
+  });
+
+  it('returns null for a non-analysis card', () => {
+    const text = `---
+title: Something else
+---
+# Something`;
+    const parsed = parseAnalysisCard(text);
+    expect(parsed).toBeNull();
+  });
+
+  it('returns null for text without frontmatter', () => {
+    const text = '# No frontmatter';
+    const parsed = parseAnalysisCard(text);
+    expect(parsed).toBeNull();
+  });
+
+  it('returns null when finding_kind is missing from frontmatter', () => {
+    const text = `---
+title: Test
+---
+# Test`;
+    const parsed = parseAnalysisCard(text);
+    expect(parsed).toBeNull();
+  });
+});

package/src/analyze/cards.ts

@@ -0,0 +1,110 @@
+/**
+ * Analysis finding card rendering and parsing for codewalker v1.4.
+ *
+ * PURE module — no I/O. Renders a Finding into a markdown card
+ * with frontmatter head (finding_kind, title, severity, location, metric, summary) and body.
+ *
+ * Cards live at entries/analysis/<finding_kind>/<slug>.md.
+ */
+
+import type { Finding, FindingKind } from "../types.ts";
+
+/**
+ * Render a Finding (coverage gap, debt, or practice) into a markdown card string.
+ *
+ * Frontmatter head includes finding_kind, title, severity, location, metric, summary.
+ * Body starts with `# <title>` and contains the full body text.
+ * Summary is the first line of the body.
+ */
+export function renderAnalysisCard(finding: {
+  finding_kind: FindingKind;
+  title: string;
+  severity?: string;
+  file_path?: string;
+  line_start?: number;
+  line_end?: number;
+  metric?: string;
+  body?: string;
+  related?: string;
+  card_path?: string;
+}): string {
+  const lines: string[] = ["---"];
+
+  addHeadField(lines, "finding_kind", finding.finding_kind);
+  addHeadField(lines, "title", finding.title);
+  if (finding.severity) addHeadField(lines, "severity", finding.severity);
+  if (finding.file_path) {
+    const location = finding.file_path + (finding.line_start && finding.line_start > 0 ? `:${finding.line_start}` : "");
+    addHeadField(lines, "location", location);
+  }
+  if (finding.metric) addHeadField(lines, "metric", finding.metric);
+  if (finding.related) addHeadField(lines, "related", finding.related);
+
+  // Summary = first line of body
+  const bodyText = finding.body ?? "";
+  const summary = bodyText.split("\n")[0]?.trim() || finding.title;
+  addHeadField(lines, "summary", summary);
+
+  lines.push("---");
+  lines.push("");
+
+  // Body
+  lines.push(`# ${finding.title}`);
+  lines.push("");
+
+  if (bodyText) {
+    lines.push(bodyText);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Parse an analysis finding card from a markdown string.
+ * Returns null if the card is invalid or not an analysis card.
+ */
+export function parseAnalysisCard(text: string): {
+  finding_kind: string;
+  title: string;
+  severity: string;
+  location: string;
+  metric: string;
+  summary: string;
+} | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("---")) return null;
+
+  const endOfFm = trimmed.indexOf("\n---", 3);
+  if (endOfFm === -1) return null;
+
+  const fmRaw = trimmed.slice(3, endOfFm).trim();
+
+  // Parse frontmatter lines into a record
+  const fm: Record<string, string> = {};
+  for (const line of fmRaw.split("\n")) {
+    const sep = line.indexOf(":");
+    if (sep > 0) {
+      const key = line.slice(0, sep).trim();
+      const value = line.slice(sep + 1).trim();
+      fm[key] = value;
+    }
+  }
+
+  if (!fm["finding_kind"]) return null;
+  if (!fm["title"]) return null;
+
+  return {
+    finding_kind: fm["finding_kind"],
+    title: fm["title"],
+    severity: fm["severity"] ?? "",
+    location: fm["location"] ?? "",
+    metric: fm["metric"] ?? "",
+    summary: fm["summary"] ?? "",
+  };
+}
+
+/** Add a key:value line to the frontmatter, sanitizing newlines. */
+function addHeadField(lines: string[], key: string, value: string): void {
+  const safe = value.replace(/\n/g, " ").trim();
+  lines.push(`${key}: ${safe}`);
+}

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([]);
+  });
+});