@aprimediet/codewalker 1.3.0 → 1.4.0

package/README.md

@@ -30,9 +30,17 @@ node_modules ──→ [.d.ts extract] ──→ LibSymbol[]
 
 agent knowledge ──→ codewalker_enrich / codewalker_note
                         ↓
-                   cards (enrichment, glossary, decisions)
+                   cards (enrichment, glossary, decisions, conventions)
                         ↓
                    index.db (notes + FTS5, unified query)
+
+coverage/*.info ──→ [coverage parser] ─┐
+source files ─────→ [debt scanner] ────┤
+agent review ─────→ codewalker_finding ─┤
+                        ↓
+                   analysis/*.md cards
+                        ↓
+                   index.db (analysis + FTS5, unified query)
 ```
 
 - **Cards are the source of truth** — markdown in `~/.pi/projects/<id>/codewalker/entries/`.
@@ -40,7 +48,9 @@ agent knowledge ──→ codewalker_enrich / codewalker_note
 - **ctags primary, regex fallback** — ctags used when available, regex for TS/JS/Py/Go.
 - **Library layer** — extracts API surface from `node_modules` `.d.ts` files (version-pinned).
 - **Semantic + bridge layer** — agent-driven enrichment, glossary terms, and decision notes.
+- **Analysis layer** — mechanical coverage and debt scanning + agent-driven best-practice review.
 - **Git-anchored** — stale index detected per query.
+- **Report, don't gate** — all analysis findings are advisory cards, never a build failure.
 
 ## Commands
 
@@ -50,6 +60,10 @@ agent knowledge ──→ codewalker_enrich / codewalker_note
 | `/codewalker sync` | Git-anchored incremental — reindexes only changed files |
 | `/codewalker query <text>` | Search the index (compact results) |
 | `/codewalker enrich <path>` | Select unenriched symbols under `<path>` and write summaries |
+| `/codewalker analyze [path]` | Mechanical coverage + debt analysis (reads lcov.info/coverage-final.json if present) |
+| `/codewalker review <path>` | Agent-driven best-practice review against conventions/decisions (capped at 25 files) |
+| `/codewalker findings [query]` | Search analysis findings with optional `--kind=coverage|debt|practice` filter |
+| `/codewalker conventions [query]` | Search coding conventions |
 | `/codewalker glossary [query]` | Search glossary terms |
 | `/codewalker decisions [query]` | Search decision notes |
 | `/codewalker libs [--dev]` | Index all direct dependencies from node_modules |
@@ -61,9 +75,10 @@ The model can call:
 
 | Tool | Description |
 |------|-------------|
-| `codewalker_query` | Search code symbols, libraries, and notes with FTS5 |
+| `codewalker_query` | Search code symbols, libraries, notes, and analysis findings with FTS5 |
 | `codewalker_enrich` | Write a one-line semantic summary back to a symbol's card + DB |
-| `codewalker_note` | Write a glossary term or decision note (bridge cards) |
+| `codewalker_note` | Write a glossary term, decision note, or coding convention |
+| `codewalker_finding` | Write a coverage, debt, or best-practice analysis finding |
 
 ## Install
 
@@ -81,7 +96,7 @@ pi -e ./node_modules/@aprimediet/codewalker/index.ts
 
 ```bash
 npm install
-npm test            # vitest — 216+ tests across 19 test files
+npm test            # vitest — 295+ tests across 25 test files
 npm run test:watch  # watch mode
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aprimediet/codewalker",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "Queryable, token-economical project & code index for the pi coding agent.",
   "keywords": ["pi-package"],

package/prompts/codewalker.md

@@ -1,9 +1,14 @@
 You have access to the codewalker code index for this project. Before reading or grepping
 files to find symbols (functions, consts, classes, types), use `codewalker_query` to
 look them up. The query returns compact facts — name, kind, file:line, and a one-line
-summary. Use `source='all'` to also surface glossary terms and decision notes.
+summary. Use `source='all'` to also surface glossary terms, decision notes, and analysis
+findings.
 
 - If the index is stale (shown in the result), run `/codewalker sync`.
 - For a full index, run `/codewalker scan`.
 - After reading an unfamiliar symbol, call `codewalker_enrich` to cache a summary.
 - When you discover a design decision or domain term, write it with `codewalker_note`.
+- When you learn a coding convention, record it with `codewalker_note type=convention`.
+- Run `/codewalker analyze` for a health snapshot (coverage gaps, debt markers).
+- Use `/codewalker review <path>` to review files against conventions and decisions,
+  writing findings with `codewalker_finding`. Findings are advisory — report, don't gate.

package/skills/codewalker/SKILL.md

@@ -43,16 +43,30 @@ Parameters:
 
 ### `codewalker_note` — Save domain knowledge
 
-Write a glossary term or design decision note. Persists as a markdown card + FTS index
-so future queries find it.
+Write a glossary term, design decision, or coding convention. Persists as a markdown
+card + FTS index so future queries find it.
 
 Parameters:
-- `type` — `glossary` | `decision`
-- `title` — glossary term or decision title
-- `body` — definition or rationale
+- `type` — `glossary` | `decision` | `convention`
+- `title` — glossary term, decision title, or convention name
+- `body` — definition, rationale, or convention description
 - `tags` — optional comma-separated tags
 - `related` — optional comma-separated symbol names or `file:line` refs
 
+### `codewalker_finding` — Write an analysis finding
+
+Write a coverage, debt, or best-practice finding. Persists as a markdown card under
+`entries/analysis/<kind>/` + FTS index. Called by the agent during a review pass.
+
+Parameters:
+- `kind` — `coverage` | `debt` | `practice`
+- `title` — short finding label
+- `file` — optional file or `file:line` the finding is about
+- `severity` — `info` | `warn` | `high` (default `info`)
+- `body` — finding detail + why it matters, grounded in conventions/decisions
+- `metric` — optional metric string, e.g. `'42%'`, `'fn length 180'`
+- `related` — optional comma-separated symbol names or `file:line` refs
+
 ---
 
 ## Commands (human-facing)
@@ -63,6 +77,10 @@ Parameters:
 | `/codewalker sync` | Git-anchored incremental update (fast) |
 | `/codewalker query <text>` | Search code symbols by name or keyword |
 | `/codewalker enrich <path> [--max=N]` | List unenriched symbols under `path` for annotation |
+| `/codewalker analyze [path]` | Mechanical coverage + debt analysis (reads lcov.info if present) |
+| `/codewalker review <path> [--max=N]` | Agent-driven best-practice review against conventions (capped 25 files) |
+| `/codewalker findings [query] [--kind=KIND]` | Search analysis findings |
+| `/codewalker conventions [query]` | Search coding conventions |
 | `/codewalker glossary [query]` | Search glossary terms |
 | `/codewalker decisions [query]` | Search decision notes |
 | `/codewalker libs [--dev]` | Index all direct npm dependencies (--dev includes devDeps) |
@@ -103,7 +121,33 @@ codewalker_note(type="decision", title="why X", body="rationale")
 ```
 These become searchable via `codewalker_query` with `source='notes'` or `source='all'`.
 
-### 6. Exploring library APIs
+### 6. Capturing coding conventions
+When you learn a project-specific coding convention, record it so reviews can measure
+against it:
+```
+codewalker_note(type="convention", title="Use functional components",
+  body="All React components must be pure functions, not classes.")
+```
+Then search them with `/codewalker conventions [query]`.
+
+### 7. Running a health snapshot
+```
+/codewalker analyze
+```
+This parses `coverage/lcov.info` (if present) and scans source files for
+TODO/FIXME/HACK markers, `@ts-ignore`, oversized files, and long functions.
+Results are queryable via `/codewalker findings [query]` or
+`codewalker_query source='analysis'`.
+
+### 8. Reviewing a subsystem against conventions
+```
+/codewalker review src/auth
+```
+This selects files under `src/auth` (capped at 25) and produces a worklist for the
+agent to review each file against the project's conventions and decisions. The agent
+calls `codewalker_finding` to write findings back.
+
+### 9. Exploring library APIs
 ```
 /codewalker libs            # index dependencies
 /codewalker lib express     # search express exports
@@ -130,4 +174,7 @@ knowledge your future self will thank you for.
 - **Cards as source of truth**: every symbol and note is stored as a markdown card file.
   The DB is rebuilt from cards on `scan` — cards are the durable artifact
 - **Source filter**: use `source='libs'` to search only library APIs, `source='notes'`
-  for glossary/decisions, `source='all'` for everything at once
+  for glossary/decisions, `source='analysis'` for findings, `source='all'` for everything
+  at once
+- **Report, don't gate**: analysis findings are advisory cards and FTS rows, never a CI
+  gate or build failure

package/src/analyze/analyzer.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { runAnalyze, rebuildAnalysisDbFromCards } from './analyzer.ts';
+import { openDb, searchFindings } from '../db.ts';
+
+describe('analyzer.ts', () => {
+  let tmpDir: string;
+  let projectRoot: string;
+  let analysisDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-analyze-'));
+    projectRoot = path.join(tmpDir, 'project');
+    analysisDir = path.join(tmpDir, 'codewalker', 'entries', 'analysis');
+    const dbDir = path.join(tmpDir, 'codewalker');
+    dbPath = path.join(dbDir, 'index.db');
+    fs.mkdirSync(analysisDir, { recursive: true });
+    fs.mkdirSync(dbDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('runAnalyze with no coverage file still produces debt findings from source scan', () => {
+    // Create a source file with debt markers
+    const srcDir = path.join(projectRoot, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(srcDir, 'a.ts'),
+      '// normal line\nconst x = 1;\n// TODO: fix this\nfunction y() { return x; }\n',
+      'utf-8'
+    );
+
+    runAnalyze({
+      projectRoot,
+      analysisDir,
+      dbPath,
+    });
+
+    // Should have debt findings
+    const db = openDb(dbPath);
+    const findings = searchFindings(db, '');
+    expect(findings.length).toBeGreaterThan(0);
+
+    // At least one should be a debt finding
+    const debtFindings = findings.filter(f => f.finding_kind === 'debt');
+    expect(debtFindings.length).toBeGreaterThan(0);
+
+    // Cards should be written
+    const debtDir = path.join(analysisDir, 'debt');
+    expect(fs.existsSync(debtDir)).toBe(true);
+    const cardFiles = fs.readdirSync(debtDir).filter(f => f.endsWith('.md'));
+    expect(cardFiles.length).toBeGreaterThan(0);
+
+    db.close();
+  });
+
+  it('runAnalyze parses coverage/lcov.info if present', () => {
+    const srcDir = path.join(projectRoot, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, 'token.ts'), 'line1\nline2\nline3\n', 'utf-8');
+
+    // Write coverage file
+    const coverageDir = path.join(projectRoot, 'coverage');
+    fs.mkdirSync(coverageDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(coverageDir, 'lcov.info'),
+      'SF:src/token.ts\nDA:1,1\nDA:2,0\nDA:3,1\nLF:3\nLH:2\nend_of_record\n',
+      'utf-8'
+    );
+
+    runAnalyze({
+      projectRoot,
+      analysisDir,
+      dbPath,
+    });
+
+    // Should have coverage findings
+    const db = openDb(dbPath);
+    const findings = searchFindings(db, '');
+    const coverageFindings = findings.filter(f => f.finding_kind === 'coverage');
+    expect(coverageFindings.length).toBeGreaterThan(0);
+
+    // Card files should be written
+    const coverageDir2 = path.join(analysisDir, 'coverage');
+    expect(fs.existsSync(coverageDir2)).toBe(true);
+
+    db.close();
+  });
+
+  it('runAnalyze parses coverage/coverage-final.json if lcov.info is absent', () => {
+    const srcDir = path.join(projectRoot, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, 'token.ts'), 'line1\nline2\n', 'utf-8');
+
+    // Write coverage-final.json
+    const coverageDir = path.join(projectRoot, 'coverage');
+    fs.mkdirSync(coverageDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(coverageDir, 'coverage-final.json'),
+      JSON.stringify({
+        'src/token.ts': {
+          path: 'src/token.ts',
+          statementMap: { '0': { start: { line: 1, column: 0 }, end: { line: 1, column: 5 } }, '1': { start: { line: 2, column: 0 }, end: { line: 2, column: 5 } } },
+          fnMap: {}, branchMap: {},
+          s: { '0': 1, '1': 0 },
+          f: {}, b: {},
+        },
+      }),
+      'utf-8'
+    );
+
+    runAnalyze({
+      projectRoot,
+      analysisDir,
+      dbPath,
+    });
+
+    const db = openDb(dbPath);
+    const findings = searchFindings(db, '');
+    const coverageFindings = findings.filter(f => f.finding_kind === 'coverage');
+    expect(coverageFindings.length).toBeGreaterThan(0);
+    db.close();
+  });
+
+  it('re-running analyze on same project does not duplicate findings', () => {
+    const srcDir = path.join(projectRoot, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), '// TODO: once\n', 'utf-8');
+
+    runAnalyze({ projectRoot, analysisDir, dbPath });
+    runAnalyze({ projectRoot, analysisDir, dbPath }); // second run
+
+    const db = openDb(dbPath);
+    const findings = searchFindings(db, '');
+    // All findings should be unique — no duplicates per (finding_kind, file_path, title)
+    const titles = findings.map(f => f.name);
+    const uniqueTitles = new Set(titles);
+    expect(titles.length).toBe(uniqueTitles.size);
+    db.close();
+  });
+
+  it('rebuildAnalysisDbFromCards reconstructs the DB from card files alone', () => {
+    // First run to create cards
+    const srcDir = path.join(projectRoot, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), '// TODO: rebuild this\nconst x = 1;\n', 'utf-8');
+
+    runAnalyze({ projectRoot, analysisDir, dbPath });
+
+    // Verify there are cards on disk
+    const debtDir = path.join(analysisDir, 'debt');
+    const cardFiles = fs.existsSync(debtDir) ? fs.readdirSync(debtDir).filter(f => f.endsWith('.md')) : [];
+    expect(cardFiles.length).toBeGreaterThan(0);
+
+    // Destroy DB and rebuild
+    const db = openDb(dbPath);
+    db.prepare('DELETE FROM analysis').run();
+    const beforeRebuild = searchFindings(db, '');
+    expect(beforeRebuild).toHaveLength(0);
+    db.close();
+
+    // Rebuild from cards
+    rebuildAnalysisDbFromCards(dbPath, analysisDir);
+
+    // Verify findings are back
+    const db2 = openDb(dbPath);
+    const afterRebuild = searchFindings(db2, '');
+    expect(afterRebuild.length).toBeGreaterThan(0);
+    expect(afterRebuild[0]!.finding_kind).toBe('debt');
+    db2.close();
+  });
+
+  it('runAnalyze reports when no coverage data is found without erroring', () => {
+    // No coverage files, no source files
+    const srcDir = path.join(projectRoot, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+
+    // Should not throw
+    expect(() => runAnalyze({ projectRoot, analysisDir, dbPath })).not.toThrow();
+
+    // With no source files either, findings should be empty
+    const db = openDb(dbPath);
+    const findings = searchFindings(db, '');
+    expect(findings).toHaveLength(0);
+    db.close();
+  });
+
+  it('runAnalyze respects a custom path filter for debt scanning', () => {
+    const srcDir = path.join(projectRoot, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), '// TODO: file a\n', 'utf-8');
+    fs.writeFileSync(path.join(srcDir, 'b.ts'), '// TODO: file b\n', 'utf-8');
+
+    runAnalyze({
+      projectRoot,
+      analysisDir,
+      dbPath,
+      pathFilter: 'src/a.ts',
+    });
+
+    const db = openDb(dbPath);
+    const findings = searchFindings(db, '');
+    const aFindings = findings.filter(f => f.file_path?.endsWith('a.ts'));
+    const bFindings = findings.filter(f => f.file_path?.endsWith('b.ts'));
+    expect(aFindings.length).toBeGreaterThan(0);
+    expect(bFindings).toHaveLength(0);
+    db.close();
+  });
+});

package/src/analyze/analyzer.ts

@@ -0,0 +1,290 @@
+/**
+ * Analysis orchestrator for codewalker v1.4.
+ *
+ * Coordinates:
+ * - Coverage parsing (lcov.info / coverage-final.json)
+ * - Debt scanning (TODO/FIXME/HACK/XXX, @ts-ignore, oversized files, long functions)
+ * - Card writing (atomic, under entries/analysis/<kind>/)
+ * - DB upsert (idempotent, per-file delete-then-insert)
+ *
+ * The agent-driven best-practice review (/codewalker review) is a separate path
+ * that uses the `review.ts` helpers and the `codewalker_finding` tool.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { openDb, upsertFinding, deleteFindingsForFile, rebuildFtsIndexes, searchFindings } from "../db.ts";
+import { parseLcov, parseCoverageJson, coverageSeverity } from "./coverage.ts";
+import { scanDebt, summarizeDebt } from "./debt.ts";
+import { renderAnalysisCard, parseAnalysisCard } from "./cards.ts";
+import type { Finding, FindingKind } from "../types.ts";
+
+export interface AnalyzeOptions {
+  /** Project root directory (source files live here). */
+  projectRoot: string;
+  /** Directory where analysis/* cards are written (entries/analysis). */
+  analysisDir: string;
+  /** Path to the SQLite DB. */
+  dbPath: string;
+  /** Optional path filter — only analyze files under this path. */
+  pathFilter?: string;
+}
+
+/** Supported file extensions for debt scanning. */
+const SUPPORTED_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+  ".py", ".go",
+]);
+
+/**
+ * Run mechanical analysis (coverage + debt) on a project.
+ *
+ * 1. Parse coverage/lcov.info or coverage/coverage-final.json if present.
+ * 2. Walk source files and scan for debt markers/heuristics.
+ * 3. Write finding cards under entries/analysis/<kind>/.
+ * 4. Upsert findings to the DB (idempotent per file).
+ */
+export function runAnalyze(options: AnalyzeOptions): { coverage: number; debt: number } {
+  const { projectRoot, analysisDir, dbPath, pathFilter } = options;
+
+  // Ensure analysis dirs exist
+  fs.mkdirSync(path.join(analysisDir, "coverage"), { recursive: true });
+  fs.mkdirSync(path.join(analysisDir, "debt"), { recursive: true });
+
+  const db = openDb(dbPath);
+  rebuildFtsIndexes(db);
+
+  const results = { coverage: 0, debt: 0 };
+
+  try {
+    // ── 1. Coverage parsing ─────────────────────────────────
+    const coverageDir = path.join(projectRoot, "coverage");
+    let coverageFiles: Finding[] = [];
+
+    if (fs.existsSync(coverageDir)) {
+      const lcovPath = path.join(coverageDir, "lcov.info");
+      const jsonPath = path.join(coverageDir, "coverage-final.json");
+
+      if (fs.existsSync(lcovPath)) {
+        const lcovText = fs.readFileSync(lcovPath, "utf-8");
+        const parsed = parseLcov(lcovText);
+        coverageFiles = parsed.map((f) => ({
+          finding_kind: "coverage" as FindingKind,
+          title: `Low coverage: ${f.file}`,
+          severity: coverageSeverity(f.pct),
+          file_path: f.file,
+          line_start: 0,
+          line_end: 0,
+          metric: `${f.pct}% (${f.lines_covered}/${f.lines_total} lines)`,
+          body: `File "${f.file}" has ${f.pct}% line coverage (${f.lines_covered}/${f.lines_total} lines covered).${
+            f.pct < 80 ? " Consider adding tests for uncovered paths." : ""
+          }`,
+          related: "",
+        }));
+      } else if (fs.existsSync(jsonPath)) {
+        const jsonText = fs.readFileSync(jsonPath, "utf-8");
+        const parsed = parseCoverageJson(JSON.parse(jsonText));
+        coverageFiles = parsed.map((f) => ({
+          finding_kind: "coverage" as FindingKind,
+          title: `Low coverage: ${f.file}`,
+          severity: coverageSeverity(f.pct),
+          file_path: f.file,
+          line_start: 0,
+          line_end: 0,
+          metric: `${f.pct}% (${f.lines_covered}/${f.lines_total} stmts)`,
+          body: `File "${f.file}" has ${f.pct}% statement coverage (${f.lines_covered}/${f.lines_total} statements covered).${
+            f.pct < 80 ? " Consider adding tests for uncovered paths." : ""
+          }`,
+          related: "",
+        }));
+      }
+
+      // Write coverage cards + upsert
+      for (const finding of coverageFiles) {
+        writeFindingCard(finding, analysisDir);
+        // Delete prior coverage findings for this file, then insert fresh
+        deleteFindingsForFile(db, "coverage", finding.file_path ?? "");
+        upsertFinding(db, {
+          ...finding,
+          severity: finding.severity,
+        });
+      }
+    }
+
+    results.coverage = coverageFiles.length;
+
+    // ── 2. Debt scanning ────────────────────────────────────
+    const sourceFiles = collectSourceFiles(projectRoot, pathFilter);
+    const existingSymbols = db.prepare(
+      "SELECT name, kind, file_path, line_start, line_end FROM symbols ORDER BY file_path, line_start",
+    ).all() as Array<{ name: string; kind: string; file_path: string; line_start: number; line_end: number }>;
+
+    for (const filePath of sourceFiles) {
+      const ext = path.extname(filePath).toLowerCase();
+      if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
+
+      const content = fs.readFileSync(filePath, "utf-8");
+      const fileSymbols = existingSymbols.filter(s => s.file_path === filePath);
+
+      const rawFindings = scanDebt(filePath, content, fileSymbols);
+      if (rawFindings.length === 0) continue;
+
+      // Delete prior debt findings for this file
+      deleteFindingsForFile(db, "debt", filePath);
+
+      // Summarize (group by marker type) and write
+      const summarized = summarizeDebt(rawFindings);
+      for (const finding of summarized) {
+        const dbFinding: Finding = {
+          finding_kind: "debt",
+          title: finding.title,
+          severity: finding.severity,
+          file_path: finding.file_path,
+          line_start: finding.line_start,
+          line_end: finding.line_end,
+          metric: finding.metric,
+          body: finding.body,
+          related: "",
+        };
+
+        writeFindingCard(dbFinding, analysisDir);
+        upsertFinding(db, dbFinding);
+      }
+
+      results.debt += summarized.length;
+    }
+  } finally {
+    db.close();
+  }
+
+  return results;
+}
+
+/**
+ * Rebuild the analysis DB tables from card files alone.
+ * Demonstrates the disposable-index property: cards are the source of truth.
+ */
+export function rebuildAnalysisDbFromCards(
+  dbPath: string,
+  analysisDir: string,
+): void {
+  const db = openDb(dbPath);
+  rebuildFtsIndexes(db);
+
+  try {
+    db.exec("BEGIN TRANSACTION");
+
+    // Clear existing analysis
+    db.prepare("DELETE FROM analysis").run();
+
+    // Walk analysis subdirectories (coverage/, debt/, practice/)
+    if (fs.existsSync(analysisDir)) {
+      for (const kindDir of fs.readdirSync(analysisDir, { withFileTypes: true })) {
+        if (!kindDir.isDirectory()) continue;
+        const kind = kindDir.name;
+        const kindPath = path.join(analysisDir, kind);
+        processAnalysisCardsInDir(db, kindPath, kind);
+      }
+    }
+
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  } finally {
+    db.close();
+  }
+}
+
+// ── Internal helpers ──────────────────────────────────────────
+
+/** Walk analysis card files in a subdirectory and upsert them to the DB. */
+function processAnalysisCardsInDir(
+  db: ReturnType<typeof openDb>,
+  dir: string,
+  expectedKind: string,
+): void {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const cardPath = path.join(dir, entry.name);
+    const cardText = fs.readFileSync(cardPath, "utf-8");
+    const parsed = parseAnalysisCard(cardText);
+    if (!parsed) continue;
+    if (parsed.finding_kind !== expectedKind) continue;
+
+    // Parse location into file_path and line_start
+    let filePath = parsed.location;
+    let lineStart = 0;
+    const locMatch = parsed.location.match(/^(.+):(\d+)$/);
+    if (locMatch) {
+      filePath = locMatch[1] ?? parsed.location;
+      lineStart = parseInt(locMatch[2] ?? "0", 10);
+    }
+
+    upsertFinding(db, {
+      finding_kind: parsed.finding_kind as FindingKind,
+      title: parsed.title,
+      severity: parsed.severity || undefined,
+      file_path: filePath,
+      line_start: lineStart,
+      line_end: 0,
+      metric: parsed.metric || undefined,
+      body: parsed.summary || undefined,
+      related: "",
+      card_path: cardPath,
+    });
+  }
+}
+
+/** Write an analysis finding card to disk (atomic write). */
+function writeFindingCard(finding: Finding, analysisDir: string): string {
+  const kindDir = path.join(analysisDir, finding.finding_kind);
+  if (!fs.existsSync(kindDir)) {
+    fs.mkdirSync(kindDir, { recursive: true });
+  }
+
+  // Generate slug from the card title
+  const slug = finding.title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || "finding";
+
+  const cardPath = path.join(kindDir, `${slug}.md`);
+  const card = renderAnalysisCard(finding);
+
+  // Atomic write
+  const tmpPath = cardPath + ".tmp";
+  fs.writeFileSync(tmpPath, card, { encoding: "utf-8", mode: 0o600 });
+  fs.renameSync(tmpPath, cardPath);
+
+  return cardPath;
+}
+
+/** Collect source files under a project root, optionally filtered by path prefix. */
+function collectSourceFiles(rootDir: string, pathFilter?: string): string[] {
+  const files: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".pi" || entry.name.startsWith(".")) continue;
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (SUPPORTED_EXTENSIONS.has(ext)) {
+          // Apply path filter if specified
+          if (pathFilter && !fullPath.includes(pathFilter)) continue;
+          files.push(fullPath);
+        }
+      }
+    }
+  };
+  if (fs.existsSync(rootDir)) {
+    walk(rootDir);
+  }
+  return files;
+}
+
+// Re-export for testing
+export { collectSourceFiles };