clud-bug 0.6.34 → 0.7.0-rc.11

package/{lib/detect.js → src/core/detect.ts}

@@ -1,7 +1,11 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { join, extname } from 'node:path';
 
-const EXT_TO_LANG = {
+// Lookup tables for the project-shape detectors. Each map is `as const` so
+// downstream consumers can rely on the value types narrowing to the literal
+// strings rather than `string` — `_internal.EXT_TO_LANG['.ts']` resolves to
+// `'typescript'` for IDE navigation, not just `string`.
+export const EXT_TO_LANG = {
   '.ts': 'typescript', '.tsx': 'typescript',
   '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
   '.py': 'python',
@@ -14,12 +18,12 @@ const EXT_TO_LANG = {
   '.cs': 'csharp',
   '.c': 'c', '.h': 'c',
   '.cpp': 'cpp', '.cc': 'cpp', '.hpp': 'cpp',
-};
+} as const satisfies Record<string, string>;
 
 // Dependency name → search term hint passed to skills.sh.
 // Only well-known frameworks; obscure packages get filtered out so the
 // skills.sh query doesn't get drowned in noise.
-const DEP_TO_TERM = {
+export const DEP_TO_TERM = {
   'next': 'nextjs', 'react': 'react', 'vue': 'vue', 'svelte': 'svelte',
   '@angular/core': 'angular', 'solid-js': 'solid',
   'express': 'express', 'fastify': 'fastify', 'koa': 'koa', 'hono': 'hono',
@@ -29,16 +33,45 @@ const DEP_TO_TERM = {
   'vitest': 'vitest', 'jest': 'jest', 'playwright': 'playwright',
   '@playwright/test': 'playwright',
   'typescript': 'typescript',
-};
+} as const satisfies Record<string, string>;
 
-const PY_DEP_TO_TERM = {
+export const PY_DEP_TO_TERM = {
   'django': 'django', 'flask': 'flask', 'fastapi': 'fastapi',
   'click': 'click', 'typer': 'typer',
   'pytest': 'pytest', 'sqlalchemy': 'sqlalchemy',
   'pydantic': 'pydantic', 'numpy': 'numpy', 'pandas': 'pandas',
-};
+} as const satisfies Record<string, string>;
 
-async function fileExists(path) {
+// Result of running every detector + post-processing — the data shape callers
+// (bin/clud-bug.js, lib/update.js) read from. `description` is nullable
+// because the README fallback may not produce anything.
+export interface DetectedSignals {
+  name: string | null;
+  description: string | null;
+  languages: string[];
+  histogram: Record<string, number>;
+  searchTerms: string[];
+  primaryLanguage: string | null;
+}
+
+// Per-detector intermediate type — what each manifest-reader returns before
+// we aggregate. `languages` is the languages each manifest implies (e.g.
+// package.json implies ['javascript']) so we can union them in detect().
+interface DetectorResult {
+  name: string | null;
+  description: string | null;
+  languages: string[];
+  terms: string[];
+}
+
+interface PackageJson {
+  name?: string;
+  description?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+async function fileExists(path: string): Promise<boolean> {
   try {
     await stat(path);
     return true;
@@ -47,15 +80,15 @@ async function fileExists(path) {
   }
 }
 
-async function readJsonSafe(path) {
+async function readJsonSafe<T = unknown>(path: string): Promise<T | null> {
   try {
-    return JSON.parse(await readFile(path, 'utf8'));
+    return JSON.parse(await readFile(path, 'utf8')) as T;
   } catch {
     return null;
   }
 }
 
-async function readTextSafe(path) {
+async function readTextSafe(path: string): Promise<string | null> {
   try {
     return await readFile(path, 'utf8');
   } catch {
@@ -63,26 +96,27 @@ async function readTextSafe(path) {
   }
 }
 
-async function detectFromPackageJson(root) {
-  const pkg = await readJsonSafe(join(root, 'package.json'));
+async function detectFromPackageJson(root: string): Promise<DetectorResult | null> {
+  const pkg = await readJsonSafe<PackageJson>(join(root, 'package.json'));
   if (!pkg) return null;
-  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-  const terms = new Set();
+  const deps: Record<string, string> = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const terms = new Set<string>();
   for (const dep of Object.keys(deps)) {
-    if (DEP_TO_TERM[dep]) terms.add(DEP_TO_TERM[dep]);
+    const term = (DEP_TO_TERM as Record<string, string>)[dep];
+    if (term) terms.add(term);
   }
   return {
-    name: pkg.name,
+    name: pkg.name ?? null,
     description: pkg.description || null,
     languages: ['javascript', ...(deps.typescript || pkg.devDependencies?.typescript ? ['typescript'] : [])],
     terms: [...terms],
   };
 }
 
-async function detectFromPyproject(root) {
+async function detectFromPyproject(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'pyproject.toml'));
   if (!text) return null;
-  const terms = new Set();
+  const terms = new Set<string>();
   for (const [dep, term] of Object.entries(PY_DEP_TO_TERM)) {
     // crude but adequate match — full TOML parse would be overkill for the
     // dependency-name lookup we actually need
@@ -91,58 +125,59 @@ async function detectFromPyproject(root) {
   const nameMatch = text.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
   const descMatch = text.match(/^\s*description\s*=\s*["']([^"']+)["']/m);
   return {
-    name: nameMatch?.[1] || null,
-    description: descMatch?.[1] || null,
+    name: nameMatch?.[1] ?? null,
+    description: descMatch?.[1] ?? null,
     languages: ['python'],
     terms: [...terms],
   };
 }
 
-async function detectFromRequirements(root) {
+async function detectFromRequirements(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'requirements.txt'));
   if (!text) return null;
-  const terms = new Set();
+  const terms = new Set<string>();
   for (const line of text.split('\n')) {
-    const dep = line.split(/[<>=~ #]/)[0].trim().toLowerCase();
-    if (PY_DEP_TO_TERM[dep]) terms.add(PY_DEP_TO_TERM[dep]);
+    const dep = (line.split(/[<>=~ #]/)[0] ?? '').trim().toLowerCase();
+    const term = (PY_DEP_TO_TERM as Record<string, string>)[dep];
+    if (term) terms.add(term);
   }
   return { name: null, description: null, languages: ['python'], terms: [...terms] };
 }
 
-async function detectFromGoMod(root) {
+async function detectFromGoMod(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'go.mod'));
   if (!text) return null;
   const moduleMatch = text.match(/^module\s+(\S+)/m);
   return {
-    name: moduleMatch?.[1]?.split('/').pop() || null,
+    name: moduleMatch?.[1]?.split('/').pop() ?? null,
     description: null,
     languages: ['go'],
     terms: [],
   };
 }
 
-async function detectFromCargo(root) {
+async function detectFromCargo(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'Cargo.toml'));
   if (!text) return null;
   const nameMatch = text.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
   const descMatch = text.match(/^\s*description\s*=\s*["']([^"']+)["']/m);
   return {
-    name: nameMatch?.[1] || null,
-    description: descMatch?.[1] || null,
+    name: nameMatch?.[1] ?? null,
+    description: descMatch?.[1] ?? null,
     languages: ['rust'],
     terms: [],
   };
 }
 
-async function detectFromGemfile(root) {
+async function detectFromGemfile(root: string): Promise<DetectorResult | null> {
   const text = await readTextSafe(join(root, 'Gemfile'));
   if (!text) return null;
   return { name: null, description: null, languages: ['ruby'], terms: [] };
 }
 
-async function fileHistogram(root) {
-  const counts = {};
-  async function walk(dir, depth) {
+async function fileHistogram(root: string): Promise<Record<string, number>> {
+  const counts: Record<string, number> = {};
+  async function walk(dir: string, depth: number): Promise<void> {
     if (depth > 3) return;
     let entries;
     try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
@@ -154,7 +189,7 @@ async function fileHistogram(root) {
       if (entry.isDirectory()) {
         await walk(full, depth + 1);
       } else {
-        const lang = EXT_TO_LANG[extname(entry.name)];
+        const lang = (EXT_TO_LANG as Record<string, string>)[extname(entry.name)];
         if (lang) counts[lang] = (counts[lang] || 0) + 1;
       }
     }
@@ -163,7 +198,7 @@ async function fileHistogram(root) {
   return counts;
 }
 
-function firstParagraph(readme) {
+function firstParagraph(readme: string | null): string | null {
   if (!readme) return null;
   const lines = readme.split('\n').slice(0, 200);
   const paragraphs = lines.join('\n').split(/\n\s*\n/);
@@ -174,20 +209,22 @@ function firstParagraph(readme) {
   return null;
 }
 
-export async function detect(root) {
+export async function detect(root: string): Promise<DetectedSignals> {
   const detectors = [
     detectFromPackageJson, detectFromPyproject, detectFromRequirements,
     detectFromGoMod, detectFromCargo, detectFromGemfile,
   ];
-  const results = (await Promise.all(detectors.map(d => d(root)))).filter(Boolean);
+  const results = (await Promise.all(detectors.map(d => d(root)))).filter(
+    (r): r is DetectorResult => r !== null,
+  );
   const histogram = await fileHistogram(root);
   const readme = await readTextSafe(join(root, 'README.md'))
     || await readTextSafe(join(root, 'README'));
 
-  const languages = new Set();
-  const terms = new Set();
-  let name = null;
-  let description = null;
+  const languages = new Set<string>();
+  const terms = new Set<string>();
+  let name: string | null = null;
+  let description: string | null = null;
   for (const r of results) {
     for (const lang of r.languages) languages.add(lang);
     for (const term of r.terms) terms.add(term);
@@ -206,12 +243,22 @@ export async function detect(root) {
     languages: sortedLangs,
     histogram,
     searchTerms: [...new Set([...terms, ...sortedLangs.slice(0, 2)])],
-    primaryLanguage: sortedLangs[0] || null,
+    primaryLanguage: sortedLangs[0] ?? null,
   };
 }
 
-export function buildDescriptionLine(signals) {
-  const parts = [];
+// Input shape for buildDescriptionLine — a subset of DetectedSignals. We
+// don't reuse DetectedSignals directly because the callers (templates,
+// LLM-flow tests) often hand-build a subset rather than running detect().
+export interface DescriptionLineSignals {
+  name?: string | null;
+  description?: string | null;
+  primaryLanguage?: string | null;
+  searchTerms?: string[];
+}
+
+export function buildDescriptionLine(signals: DescriptionLineSignals): string {
+  const parts: string[] = [];
   if (signals.name) parts.push(`This project is "${signals.name}".`);
   if (signals.description) {
     // v0.6.25 / issue #89: when signals.description comes from a
@@ -226,7 +273,7 @@ export function buildDescriptionLine(signals) {
     parts.push(/[.!?]$/.test(desc) ? desc : `${desc}.`);
   }
   if (signals.primaryLanguage) {
-    const frameworks = [...new Set(signals.searchTerms)].filter(t =>
+    const frameworks = [...new Set(signals.searchTerms || [])].filter((t) =>
       !['typescript', 'javascript', 'python', 'go', 'rust', 'ruby'].includes(t));
     const frameworkPart = frameworks.length ? ` using ${frameworks.join(', ')}` : '';
     parts.push(`It's primarily ${signals.primaryLanguage}${frameworkPart}.`);
@@ -235,5 +282,11 @@ export function buildDescriptionLine(signals) {
   return parts.join(' ');
 }
 
-// Test seam: allow tests to inject the EXT_TO_LANG and DEP_TO_TERM tables
-export const _internal = { EXT_TO_LANG, DEP_TO_TERM, PY_DEP_TO_TERM, fileHistogram, firstParagraph };
+// Architect's anti-pattern fix (Phase 2): the JS source used a single
+// `export const _internal = { … }` namespace as a test seam. The TS port
+// promotes the table exports (EXT_TO_LANG, DEP_TO_TERM, PY_DEP_TO_TERM)
+// to direct top-level exports, and exposes the two helper functions
+// fileHistogram + firstParagraph as direct named exports too. Tests now
+// import each symbol by name. No `_internal` re-export — that pattern is
+// gone.
+export { fileHistogram, firstParagraph };

package/src/core/diff-findings.ts

@@ -0,0 +1,323 @@
+// SPEC §1.8.1 multi-pass diff: prior `docs/reviews/PR-<n>.md` vs current
+// review findings. Produces the `**Resolved this round:**` /
+// `**Still open:**` lists that `renderReviewFile` consumes.
+//
+// Identity model
+// --------------
+// Each finding's identity is a stable hash of:
+//
+//   `${file}:${line}:${severity}:${skillName}:${summary.slice(0, 100)}`
+//
+// A 100-character truncation on `summary` is enough to discriminate
+// distinct findings without being so long that whitespace/punctuation
+// drift between passes breaks identity. A severity-bucket change (e.g.
+// the same skill flags the same line as 🔴 then 🟡 the next round)
+// produces a DIFFERENT identity — by design — so a severity downgrade
+// counts as one resolved finding + one new finding (the user gets
+// credit for the fix AND can see the bot still has a concern, just at
+// a lower severity).
+//
+// The same identity shape is what auto-fix / auto-resolve in
+// clud-bug-app uses for thread anchoring; keeping it identical means a
+// future per-finding cross-reference between the doc-file diff and the
+// inline-thread surface is trivial.
+
+import {
+  flattenFindings,
+  type Finding,
+  type Review,
+} from './review-schema-zod.js';
+
+import { SEVERITY_EMOJI } from './review-writeback.js';
+
+/** One parsed finding from a prior `docs/reviews/PR-<n>.md`. */
+export type ParsedFinding = {
+  /** Relative path. Falls back to '(unknown file)' when the prior file
+   *  itself rendered the unknown-file marker; we keep it intact for
+   *  identity stability. */
+  file: string;
+  /**
+   * 1-indexed line number. Zero when the prior file had no `:N` suffix
+   * (cross-cutting findings). Zero participates in identity as-is.
+   */
+  line: number;
+  severity: 'critical' | 'minor' | 'preexisting';
+  skillName: string;
+  summary: string;
+};
+
+export type ParsedReview = { findings: ParsedFinding[] };
+
+/**
+ * Parse a `docs/reviews/PR-<n>.md` markdown back into structured findings.
+ *
+ * Robust to:
+ *   - `null` / `undefined` input            → returns `null`
+ *   - empty / whitespace-only markdown      → returns `null`
+ *   - missing severity sections             → those sections contribute 0
+ *   - lines that don't match the SPEC bullet shape → silently dropped
+ *   - mixed unknown-file markers (`(unknown file)` vs absent)
+ *
+ * Parsing strategy: walk top-down, switch active severity on each
+ * `### <emoji> <Label>` header (one of the three SPEC §1.8.1 buckets),
+ * then collect every line starting with `- **` until the next header
+ * (or `---` end marker). Each `- **<file>:<line>** — <skill>: <summary>`
+ * line is split into its 4 fields; `:<line>` is optional (cross-cutting).
+ *
+ * `(unknown file)` files are preserved verbatim — they participate in
+ * identity, so the same cross-cutting finding can still be diffed across
+ * rounds even when neither pass has a line anchor.
+ */
+export function parsePriorReviewFile(
+  markdown: string | null | undefined,
+): ParsedReview | null {
+  if (markdown == null) return null;
+  if (markdown.trim() === '') return null;
+
+  const lines = markdown.split('\n');
+  const out: ParsedFinding[] = [];
+  let current: ParsedFinding['severity'] | null = null;
+
+  for (const raw of lines) {
+    // Strip trailing whitespace; leading indent is meaningful for
+    // sub-lines (Reasoning, attribution) which we deliberately ignore.
+    const line = raw.replace(/\s+$/, '');
+
+    // The SPEC §1.8.1 trailing `---` separator ends the findings region.
+    // Anything after it (the [Link to PR] line) is metadata and parsed
+    // by short-circuit so we don't mistake the literal `---` for a
+    // missing header.
+    if (line === '---') {
+      current = null;
+      continue;
+    }
+
+    // Switch active severity on every `### <emoji> <Label>` heading.
+    // We pattern-match on the emoji codepoint (not the label text) so a
+    // future SPEC tweak to "Critical" → "Blocking" doesn't break us.
+    if (line.startsWith('### ')) {
+      if (line.includes(SEVERITY_EMOJI.critical)) {
+        current = 'critical';
+      } else if (line.includes(SEVERITY_EMOJI.minor)) {
+        current = 'minor';
+      } else if (line.includes(SEVERITY_EMOJI.preexisting)) {
+        current = 'preexisting';
+      } else {
+        current = null;
+      }
+      continue;
+    }
+
+    // Resolved / Still-open blocks under SPEC §1.8.1 — these list
+    // findings from PRIOR rounds, NOT this-round findings. Skip them
+    // so a multi-round PR doesn't double-count its own history.
+    // (`**Resolved this round:**` / `**Still open:**` headings.)
+    if (line.startsWith('**Resolved this round:') || line.startsWith('**Still open:')) {
+      current = null;
+      continue;
+    }
+
+    if (current == null) continue;
+
+    // SPEC §1.8.1 bullet: `- **<file>:<line>** — <skill>: <summary>`
+    //                  OR `- **<file>** — <skill>: <summary>`
+    //                  OR `- **(unknown file)** — <skill>: <summary>`
+    //
+    // The multi-pass renderer prepends `[Pass N — Role · model]` to the
+    // bullet; we accept that prefix and discard it for parsing.
+    const parsed = parseFindingBullet(line);
+    if (parsed) {
+      out.push({ ...parsed, severity: current });
+    }
+  }
+
+  if (out.length === 0) return null;
+  return { findings: out };
+}
+
+/**
+ * Diff prior vs current.
+ *
+ * `resolvedFindings`: findings that appeared in `prior` but NOT in
+ * `current`. The PR author (or auto-fix) addressed them.
+ *
+ * `stillOpenFindings`: findings that appeared in BOTH `prior` and
+ * `current`. These are persistent — the PR author hasn't fixed them
+ * (or the bot still considers them findings post-fix-push).
+ *
+ * Findings unique to `current` (newly raised this round) appear in
+ * neither list — those are surfaced directly by the renderer's normal
+ * severity-bucket emission.
+ *
+ * Order is preserved from `prior` for stability across rounds.
+ */
+export function diffFindings(
+  prior: ParsedReview | null,
+  current: {
+    critical_findings?: Array<{
+      skill: string;
+      file?: string;
+      line?: number;
+      summary: string;
+    }>;
+    minor_findings?: Array<{
+      skill: string;
+      file?: string;
+      line?: number;
+      summary: string;
+    }>;
+    preexisting_findings?: Array<{
+      skill: string;
+      file?: string;
+      line?: number;
+      summary: string;
+    }>;
+  },
+): {
+  resolvedFindings: ParsedFinding[];
+  stillOpenFindings: ParsedFinding[];
+} {
+  if (prior === null || prior.findings.length === 0) {
+    return { resolvedFindings: [], stillOpenFindings: [] };
+  }
+
+  // Build identity set for the current round. We do not need the
+  // current-round ParsedFinding objects — we only need to know which
+  // identities are still present.
+  //
+  // Cast through `Review` shape — the schema's three arrays mirror our
+  // input slice exactly (skill / file / line / summary), so we can lean
+  // on `flattenFindings` to produce a tagged list.
+  const currentReview: Review = {
+    status_header: 'clean',
+    summary_counts: {
+      critical: 0,
+      minor: 0,
+      preexisting: 0,
+      resolved_from_prior: 0,
+      still_open: 0,
+    },
+    per_skill_scan: [],
+    critical_findings: current.critical_findings ?? [],
+    minor_findings: current.minor_findings ?? [],
+    preexisting_findings: current.preexisting_findings ?? [],
+    skills_referenced: [],
+    last_reviewed_sha: '',
+  };
+  const currentFlat: Finding[] = flattenFindings(currentReview);
+  const currentIds = new Set<string>(currentFlat.map((f) => findingIdentity({
+    file: f.file ?? '(unknown file)',
+    line: f.line ?? 0,
+    severity: f.severity,
+    skillName: f.skill,
+    summary: f.summary,
+  })));
+
+  const resolved: ParsedFinding[] = [];
+  const stillOpen: ParsedFinding[] = [];
+  for (const f of prior.findings) {
+    const id = findingIdentity(f);
+    if (currentIds.has(id)) {
+      stillOpen.push(f);
+    } else {
+      resolved.push(f);
+    }
+  }
+  return { resolvedFindings: resolved, stillOpenFindings: stillOpen };
+}
+
+/**
+ * Stable identity for a finding. Used for diffing prior vs current
+ * across review rounds AND (by intention) shareable with the
+ * clud-bug-app inline-thread anchor hash so future cross-feature
+ * surfaces (e.g. "the auto-fix that resolved this thread also resolves
+ * this doc-file finding") align without re-computing.
+ *
+ * Exposed for tests + downstream callers that want to align their own
+ * finding storage on the same scheme.
+ */
+export function findingIdentity(f: {
+  file: string;
+  line: number;
+  severity: 'critical' | 'minor' | 'preexisting';
+  skillName: string;
+  summary: string;
+}): string {
+  // Truncate summary to 100 chars to absorb whitespace/punctuation
+  // drift between rounds without losing discrimination between
+  // genuinely-distinct findings (the SPEC §1.8.1 summary line is
+  // user-visible so it tends to be stable; 100 chars is enough for any
+  // realistic distinct summary while tolerating "fix the X" → "fix X"
+  // drift).
+  const summaryPart = f.summary.slice(0, 100);
+  return `${f.file}:${f.line}:${f.severity}:${f.skillName}:${summaryPart}`;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing internals
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse one SPEC §1.8.1 bullet line into a {file, line, skill, summary}
+ * tuple. Returns null for any line that doesn't match the SPEC shape.
+ *
+ * Accepts both shapes:
+ *   `- **<file>:<line>** — <skill>: <summary>`
+ *   `- **<file>** — <skill>: <summary>`
+ *
+ * Also tolerates the multi-pass attribution prefix (D.2.5):
+ *   `- [Pass 1 — Role · model] **<file>:<line>** — <skill>: <summary>`
+ *
+ * Em-dash recognition: the SPEC pins U+2014 EM DASH between location
+ * and skill. Some downstream tools have been observed using `--` or
+ * regular hyphens; we accept both for resilience.
+ */
+function parseFindingBullet(line: string): Omit<ParsedFinding, 'severity'> | null {
+  // Strip the leading `- ` bullet marker.
+  if (!line.startsWith('- ')) return null;
+  let rest = line.slice(2);
+
+  // Strip optional `[Pass N — ...] ` attribution prefix (D.2.5).
+  if (rest.startsWith('[')) {
+    const closeIdx = rest.indexOf('] ');
+    if (closeIdx === -1) return null;
+    rest = rest.slice(closeIdx + 2);
+  }
+
+  // Expect `**<location>** ` next.
+  if (!rest.startsWith('**')) return null;
+  const locEnd = rest.indexOf('**', 2);
+  if (locEnd === -1) return null;
+  const location = rest.slice(2, locEnd);
+  rest = rest.slice(locEnd + 2);
+
+  // Strip the location separator. SPEC pins ` — ` (U+2014 surrounded by
+  // spaces). We accept hyphen-minus variants as a courtesy.
+  // The separator may be ` — `, ` -- `, or ` - `.
+  const sepMatch = rest.match(/^\s+(?:—|--|-)\s+/);
+  if (!sepMatch) return null;
+  rest = rest.slice(sepMatch[0].length);
+
+  // `<skill>: <summary>` — split on the first `: `.
+  const sepIdx = rest.indexOf(': ');
+  if (sepIdx === -1) return null;
+  const skillName = rest.slice(0, sepIdx).trim();
+  const summary = rest.slice(sepIdx + 2).trim();
+  if (skillName === '' || summary === '') return null;
+
+  // Split location into file + optional line. Walk RIGHTWARD from the
+  // last `:` so file names containing colons (Windows-style, rare) on
+  // the LHS don't confuse us.
+  const colonIdx = location.lastIndexOf(':');
+  let file = location;
+  let lineNum = 0;
+  if (colonIdx !== -1) {
+    const tail = location.slice(colonIdx + 1);
+    if (/^\d+$/.test(tail)) {
+      file = location.slice(0, colonIdx);
+      lineNum = Number(tail);
+    }
+  }
+
+  return { file, line: lineNum, skillName, summary };
+}