purecontext-mcp 1.1.8 → 1.2.0

package/dist/server/tools/find-untested-symbols.js

@@ -0,0 +1,308 @@
+/**
+ * find-untested-symbols.ts
+ *
+ * MCP tool: find_untested_symbols
+ *
+ * Identifies exported symbols (functions, methods, classes, etc.) in the
+ * codebase that do not appear to have any test coverage — i.e. whose names
+ * are not referenced in any test file.
+ *
+ * Detection strategy (static heuristic):
+ *   1. Identify test files by path convention:
+ *      - Path segment is "test", "tests", "spec", "specs", or "__tests__"
+ *      - Filename ends with .test.*, .spec.*, _test.*, or _spec.*
+ *   2. Extract all identifiers referenced in those test files.
+ *   3. Any non-test symbol whose name does NOT appear in the test identifier
+ *      set is considered "untested".
+ *
+ * Limitations:
+ *   - Name-based matching only; dynamic dispatch, aliases, and indirect calls
+ *     can produce false negatives (symbol appears tested when it is not) or
+ *     false positives (common names like `get` match unrelated things).
+ *   - Does not read coverage reports; for accurate coverage, pipe in a
+ *     coverage JSON file via get_test_coverage_map instead.
+ *
+ * Priority rating (per untested symbol):
+ *   high   — cyclomatic_complexity >= 5 OR line_count >= 20
+ *   medium — cyclomatic_complexity >= 2 OR line_count >= 8
+ *   low    — all other symbols
+ */
+import { z } from 'zod';
+import { openDatabase, getRepo } from '../../core/db/schema.js';
+import { buildMeta } from './_meta.js';
+export const name = 'find_untested_symbols';
+export const description = 'Identify symbols (functions, methods, classes) that do not appear to have ' +
+    'test coverage by scanning test files for references to each symbol name. ' +
+    'Returns a prioritised list of untested symbols ranked by cyclomatic ' +
+    'complexity so you can focus testing effort where it matters most.' +
+    '\n\nDetection strategy: static heuristic — symbol name must appear as an ' +
+    'identifier in at least one test file (path-based detection). ' +
+    'This is not a coverage-report parser; use get_test_coverage_map for ' +
+    'line-level accuracy.' +
+    '\n\nDiffers from related tools:' +
+    '\n  find_dead_code        — exports with no importers (unused API)' +
+    '\n  get_test_coverage_map — line-level coverage from a coverage JSON report' +
+    '\n  get_complexity_hotspots — complexity ranking without test-coverage filter';
+// ─── Default testable kinds ────────────────────────────────────────────────────
+const DEFAULT_KINDS = ['function', 'method', 'class', 'interface', 'middleware', 'route'];
+// ─── Input schema ──────────────────────────────────────────────────────────────
+export const inputSchema = {
+    repoId: z.string().describe('Repository ID returned by index_folder or list_repos'),
+    scope: z
+        .string()
+        .optional()
+        .describe('Restrict analysis to a directory prefix (e.g. "src/services/"). ' +
+        'Omit to analyse the whole repo.'),
+    kinds: z
+        .array(z.string())
+        .optional()
+        .describe(`Symbol kinds to include (default: ${DEFAULT_KINDS.join(', ')}). ` +
+        'Narrow to e.g. ["function","method"] to focus on callable units.'),
+    filePath: z
+        .string()
+        .optional()
+        .describe('Restrict to a specific source file path (relative to repo root).'),
+    minLineCount: z
+        .number().int().min(1)
+        .optional()
+        .describe('Minimum symbol line count to include (default 3). ' +
+        'Filters out trivial one-liners that are not worth testing individually.'),
+    includeTestRefs: z
+        .boolean()
+        .optional()
+        .describe('When true, include the list of test files that reference each ' +
+        'symbol (the "testRefs" field). Increases response size. Default false.'),
+    limit: z
+        .number().int().min(1).max(500)
+        .optional()
+        .describe('Maximum number of untested symbols to return (default 50).'),
+};
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+/**
+ * Returns true when a file path looks like a test file by convention.
+ */
+function isTestFile(filePath) {
+    // Normalise separators
+    const norm = filePath.replace(/\\/g, '/');
+    // Path-segment match: /test/, /tests/, /spec/, /specs/, /__tests__/
+    if (/(?:^|\/)(?:tests?|specs?|__tests__)\//.test(norm))
+        return true;
+    // Filename suffix: .test.ts, .spec.ts, .test.js, _test.go, etc.
+    if (/[._](?:test|spec)\.[a-z]+$/.test(norm))
+        return true;
+    // Filename prefix: test_foo.py, spec_foo.rb
+    const filename = norm.split('/').pop() ?? '';
+    if (/^(?:test|spec)_/.test(filename))
+        return true;
+    return false;
+}
+/**
+ * Extract all identifier tokens from source text.
+ * Returns a Set for O(1) membership checks.
+ */
+function extractIdentifiers(text) {
+    const ids = new Set();
+    for (const m of text.matchAll(/\b([A-Za-z_$][A-Za-z0-9_$]*)\b/g)) {
+        ids.add(m[1]);
+    }
+    return ids;
+}
+/**
+ * Assign a priority to an untested symbol based on its complexity and size.
+ */
+function computePriority(cc, lineCount) {
+    if (cc >= 5 || lineCount >= 20)
+        return 'high';
+    if (cc >= 2 || lineCount >= 8)
+        return 'medium';
+    return 'low';
+}
+/**
+ * Compute the 1-based line number for a given byte offset in a buffer.
+ */
+function lineOf(buf, startByte) {
+    const slice = buf.slice(0, Math.min(startByte, buf.length));
+    let line = 1;
+    for (let i = 0; i < slice.length; i++) {
+        if (slice[i] === 0x0a)
+            line++;
+    }
+    return line;
+}
+// ─── Handler ───────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { repoId, minLineCount = 3, includeTestRefs = false, limit = 50, } = args;
+    const kinds = (args.kinds && args.kinds.length > 0)
+        ? args.kinds
+        : DEFAULT_KINDS;
+    const db = openDatabase(repoId);
+    try {
+        // ── Validate repo ─────────────────────────────────────────────────────────
+        const repo = getRepo(db, repoId);
+        if (!repo) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `Repo "${repoId}" not found. Run index_folder first.` }),
+                    }],
+                isError: true,
+            };
+        }
+        // ── Load all indexed files (with content) ─────────────────────────────────
+        const allFiles = db
+            .prepare('SELECT path, raw_content FROM files WHERE repo_id = ?')
+            .all(repoId);
+        // ── Partition files: test vs source ───────────────────────────────────────
+        const testFiles = [];
+        for (const f of allFiles) {
+            if (isTestFile(f.path))
+                testFiles.push(f);
+        }
+        // ── Build identifier sets per test file ───────────────────────────────────
+        // identifiersByTestFile[i] = Set of identifiers in testFiles[i]
+        const identifiersByTestFile = [];
+        // Global union for fast "is this symbol name referenced at all?" check
+        const allTestIdentifiers = new Set();
+        for (const tf of testFiles) {
+            if (!tf.raw_content)
+                continue;
+            const text = tf.raw_content.toString('utf8');
+            const ids = extractIdentifiers(text);
+            identifiersByTestFile.push({ path: tf.path, ids });
+            for (const id of ids)
+                allTestIdentifiers.add(id);
+        }
+        // ── Load candidate symbols ────────────────────────────────────────────────
+        const kindPlaceholders = kinds.map(() => '?').join(', ');
+        const conditions = [
+            'repo_id = ?',
+            `kind IN (${kindPlaceholders})`,
+            'COALESCE(line_count, 1) >= ?',
+        ];
+        const params = [repoId, ...kinds, minLineCount];
+        if (args.scope) {
+            const prefix = args.scope.endsWith('/') ? args.scope : `${args.scope}/`;
+            conditions.push('(file_path = ? OR file_path LIKE ?)');
+            params.push(args.scope, `${prefix}%`);
+        }
+        if (args.filePath) {
+            conditions.push('file_path = ?');
+            params.push(args.filePath);
+        }
+        const sql = `
+      SELECT id, name, kind, file_path, start_byte, signature, summary,
+             COALESCE(line_count, 1)           AS line_count,
+             COALESCE(cyclomatic_complexity, 1) AS cyclomatic_complexity
+      FROM symbols
+      WHERE ${conditions.join(' AND ')}
+        AND file_path NOT IN (SELECT path FROM files WHERE repo_id = ? AND path IN (
+          ${allFiles.filter(f => isTestFile(f.path)).map(() => '?').join(',') || 'SELECT NULL'}
+        ))
+      ORDER BY cyclomatic_complexity DESC, line_count DESC
+    `;
+        // Avoid building a huge IN clause for test-file exclusion — instead
+        // filter in JS after the query (simpler and still fast for typical repos).
+        const sqlSimple = `
+      SELECT id, name, kind, file_path, start_byte, signature, summary,
+             COALESCE(line_count, 1)           AS line_count,
+             COALESCE(cyclomatic_complexity, 1) AS cyclomatic_complexity
+      FROM symbols
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY cyclomatic_complexity DESC, line_count DESC
+    `;
+        void sql; // suppress unused-variable warning for the filtered version above
+        const allSymbols = db
+            .prepare(sqlSimple)
+            .all(params);
+        // Exclude symbols that live in test files
+        const testFilePaths = new Set(testFiles.map((f) => f.path));
+        const sourceSymbols = allSymbols.filter((s) => !testFilePaths.has(s.file_path));
+        // ── Classify each symbol ──────────────────────────────────────────────────
+        const untestedSymbols = [];
+        let testedCount = 0;
+        // Cache file buffers for line computation
+        const fileBufferCache = new Map();
+        const getFileBuffer = (filePath) => {
+            if (fileBufferCache.has(filePath))
+                return fileBufferCache.get(filePath) ?? null;
+            const row = db
+                .prepare('SELECT raw_content FROM files WHERE repo_id = ? AND path = ?')
+                .get(repoId, filePath);
+            const buf = row?.raw_content ?? null;
+            if (buf)
+                fileBufferCache.set(filePath, buf);
+            return buf;
+        };
+        for (const sym of sourceSymbols) {
+            const isTested = allTestIdentifiers.has(sym.name);
+            if (isTested) {
+                testedCount++;
+                continue;
+            }
+            // Build start line
+            const buf = getFileBuffer(sym.file_path);
+            const startLine = buf ? lineOf(buf, sym.start_byte) : 1;
+            const cc = sym.cyclomatic_complexity ?? 1;
+            const lc = sym.line_count ?? 1;
+            const entry = {
+                symbolId: sym.id,
+                name: sym.name,
+                kind: sym.kind,
+                filePath: sym.file_path,
+                startLine,
+                signature: sym.signature,
+                summary: sym.summary,
+                lineCount: lc,
+                cyclomaticComplexity: cc,
+                priority: computePriority(cc, lc),
+            };
+            if (includeTestRefs) {
+                // For untested symbols, testRefs is empty (none reference it)
+                entry.testRefs = [];
+            }
+            untestedSymbols.push(entry);
+        }
+        const truncated = untestedSymbols.length > limit;
+        const visibleUntested = untestedSymbols.slice(0, limit);
+        // ── Summary ───────────────────────────────────────────────────────────────
+        const totalSymbols = sourceSymbols.length;
+        const untestedCount = untestedSymbols.length;
+        const testCoverageRate = totalSymbols > 0
+            ? Math.round(((testedCount) / totalSymbols) * 1000) / 1000
+            : 1;
+        const highCount = untestedSymbols.filter((s) => s.priority === 'high').length;
+        const mediumCount = untestedSymbols.filter((s) => s.priority === 'medium').length;
+        const lowCount = untestedSymbols.filter((s) => s.priority === 'low').length;
+        // ── Token estimate ─────────────────────────────────────────────────────────
+        const tokenEstimate = Math.ceil(visibleUntested.reduce((sum, s) => sum + s.signature.length + s.summary.length + s.filePath.length + 80, 0) / 4);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        repoId,
+                        totalSymbols,
+                        testedCount,
+                        untestedCount,
+                        testCoverageRate,
+                        testFilesScanned: testFiles.length,
+                        truncated,
+                        untestedSymbols: visibleUntested,
+                        summary: {
+                            highPriority: highCount,
+                            mediumPriority: mediumCount,
+                            lowPriority: lowCount,
+                            kindsAnalyzed: kinds,
+                            minLineCount,
+                        },
+                        _tokenEstimate: tokenEstimate,
+                        _meta: buildMeta({ timingMs: Date.now() - t0 }),
+                    }, null, 2),
+                }],
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=find-untested-symbols.js.map

package/dist/server/tools/find-untested-symbols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-untested-symbols.js","sourceRoot":"","sources":["../../../src/server/tools/find-untested-symbols.ts"],"names":[],"mappings":"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"}

package/dist/server/tools/get-architecture-snapshot.d.ts

@@ -0,0 +1,43 @@
+/**
+ * get-architecture-snapshot.ts
+ *
+ * MCP tool: get_architecture_snapshot
+ *
+ * Freeze the current architecture state (dep graph topology + quality metrics)
+ * into a named snapshot, and diff two snapshots to show what changed structurally
+ * between commits or dates.
+ *
+ * Actions:
+ *   'create' — compute current metrics, store as a snapshot row
+ *   'list'   — return all snapshots for the repo, newest first
+ *   'diff'   — compare two snapshot records and return deltas
+ *   'delete' — remove a snapshot by ID
+ *
+ * Storage: `snapshots` table in SQLite — stores aggregated metrics as a JSON
+ * blob plus the file list (for filesAdded/filesRemoved diffing).
+ * No full graph copies are stored.
+ */
+import { z } from 'zod';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const name = "get_architecture_snapshot";
+export declare const description: string;
+export declare const inputSchema: {
+    repoId: z.ZodString;
+    action: z.ZodEnum<{
+        delete: "delete";
+        create: "create";
+        diff: "diff";
+        list: "list";
+    }>;
+    snapshotId: z.ZodOptional<z.ZodString>;
+    compareId: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+};
+export declare function handler(args: {
+    repoId: string;
+    action: 'create' | 'list' | 'diff' | 'delete';
+    snapshotId?: string;
+    compareId?: string;
+    label?: string;
+}): Promise<CallToolResult>;
+//# sourceMappingURL=get-architecture-snapshot.d.ts.map

package/dist/server/tools/get-architecture-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-architecture-snapshot.d.ts","sourceRoot":"","sources":["../../../src/server/tools/get-architecture-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,eAAO,MAAM,IAAI,8BAA8B,CAAC;AAEhD,eAAO,MAAM,WAAW,QAOqB,CAAC;AAE9C,eAAO,MAAM,WAAW;;;;;;;;;;;CAiBvB,CAAC;AAsJF,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,cAAc,CAAC,CAwM1B"}

package/dist/server/tools/get-architecture-snapshot.js

@@ -0,0 +1,292 @@
+/**
+ * get-architecture-snapshot.ts
+ *
+ * MCP tool: get_architecture_snapshot
+ *
+ * Freeze the current architecture state (dep graph topology + quality metrics)
+ * into a named snapshot, and diff two snapshots to show what changed structurally
+ * between commits or dates.
+ *
+ * Actions:
+ *   'create' — compute current metrics, store as a snapshot row
+ *   'list'   — return all snapshots for the repo, newest first
+ *   'diff'   — compare two snapshot records and return deltas
+ *   'delete' — remove a snapshot by ID
+ *
+ * Storage: `snapshots` table in SQLite — stores aggregated metrics as a JSON
+ * blob plus the file list (for filesAdded/filesRemoved diffing).
+ * No full graph copies are stored.
+ */
+import { z } from 'zod';
+import { randomBytes } from 'crypto';
+import { openDatabase, getRepo } from '../../core/db/schema.js';
+import { getCouplingMap } from '../../core/db/dep-store.js';
+import { findImportCycles } from '../../graph/graph-traversal.js';
+import { buildMeta } from './_meta.js';
+export const name = 'get_architecture_snapshot';
+export const description = 'Freeze the current architecture state into a named snapshot, then diff two snapshots ' +
+    'to measure structural change over time. ' +
+    'action "create": compute fileCount, symbolCount, edgeCount, cycleCount, avgCoupling, ' +
+    'avgComplexity and store them with an optional label. ' +
+    'action "list": return all snapshots for the repo, newest first. ' +
+    'action "diff": compare two snapshots and return deltas (cycleCountDelta < 0 means fewer cycles — good). ' +
+    'action "delete": remove a snapshot by ID.';
+export const inputSchema = {
+    repoId: z.string().describe('Repo ID from index_folder or resolve_repo'),
+    action: z
+        .enum(['create', 'list', 'diff', 'delete'])
+        .describe('"create" | "list" | "diff" | "delete"'),
+    snapshotId: z
+        .string()
+        .optional()
+        .describe('Snapshot ID — required for diff (snapshotId = base) and delete'),
+    compareId: z
+        .string()
+        .optional()
+        .describe('The second snapshot ID to compare against — required for diff'),
+    label: z
+        .string()
+        .optional()
+        .describe('Human-readable label for the snapshot (e.g. "before-auth-refactor")'),
+};
+function ensureSnapshotsTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS snapshots (
+      snapshot_id  TEXT    NOT NULL,
+      repo_id      TEXT    NOT NULL,
+      label        TEXT    NOT NULL DEFAULT '',
+      created_at   INTEGER NOT NULL,
+      metrics      TEXT    NOT NULL,
+      PRIMARY KEY (snapshot_id, repo_id),
+      FOREIGN KEY (repo_id) REFERENCES repos(id) ON DELETE CASCADE
+    )
+  `);
+    try {
+        db.exec('CREATE INDEX IF NOT EXISTS idx_snapshots_repo ON snapshots(repo_id, created_at)');
+    }
+    catch {
+        // already exists
+    }
+}
+function rowToRecord(row) {
+    const m = JSON.parse(row.metrics);
+    return {
+        snapshotId: row.snapshot_id,
+        label: row.label,
+        createdAt: new Date(row.created_at).toISOString(),
+        fileCount: m.fileCount,
+        symbolCount: m.symbolCount,
+        edgeCount: m.edgeCount,
+        cycleCount: m.cycleCount,
+        avgCoupling: m.avgCoupling,
+        avgComplexity: m.avgComplexity,
+    };
+}
+// ─── Metrics computation ──────────────────────────────────────────────────────
+function computeMetrics(db, repoId) {
+    // File count
+    const fileRow = db
+        .prepare('SELECT COUNT(*) AS n FROM files WHERE repo_id = ?')
+        .get(repoId);
+    const fileCount = fileRow?.n ?? 0;
+    // Symbol count
+    const symRow = db
+        .prepare('SELECT COUNT(*) AS n FROM symbols WHERE repo_id = ?')
+        .get(repoId);
+    const symbolCount = symRow?.n ?? 0;
+    // Edge count
+    const edgeRow = db
+        .prepare('SELECT COUNT(*) AS n FROM dep_edges WHERE repo_id = ?')
+        .get(repoId);
+    const edgeCount = edgeRow?.n ?? 0;
+    // File paths list
+    const filePaths = db
+        .prepare('SELECT path FROM files WHERE repo_id = ? ORDER BY path')
+        .all(repoId)
+        .map((r) => r.path);
+    // Cycle count — use DFS-based findImportCycles, cap at 500
+    const cyclesResult = findImportCycles(repoId, db, undefined, 500);
+    const cycleCount = cyclesResult.cycles.length;
+    // Average coupling (efferent + afferent per file / 2 averaged across files)
+    const couplingRows = getCouplingMap(db, repoId);
+    let avgCoupling = 0;
+    if (couplingRows.length > 0) {
+        const totalCoupling = couplingRows.reduce((sum, r) => sum + r.efferentCoupling + r.afferentCoupling, 0);
+        avgCoupling = Math.round((totalCoupling / couplingRows.length) * 100) / 100;
+    }
+    // Average cyclomatic complexity from indexed symbols (skip NULLs)
+    const complexityRow = db
+        .prepare('SELECT AVG(cyclomatic_complexity) AS avg FROM symbols WHERE repo_id = ? AND cyclomatic_complexity IS NOT NULL')
+        .get(repoId);
+    const avgComplexity = complexityRow?.avg != null
+        ? Math.round(complexityRow.avg * 100) / 100
+        : 0;
+    return { fileCount, symbolCount, edgeCount, cycleCount, avgCoupling, avgComplexity, files: filePaths };
+}
+// ─── Handler ──────────────────────────────────────────────────────────────────
+export async function handler(args) {
+    const t0 = Date.now();
+    const { repoId, action, snapshotId, compareId, label = '' } = args;
+    const db = openDatabase(repoId);
+    try {
+        const repo = getRepo(db, repoId);
+        if (!repo) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: `Repo "${repoId}" not found. Run index_folder first.` }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Ensure the snapshots table exists (safe with IF NOT EXISTS)
+        ensureSnapshotsTable(db);
+        if (action === 'create') {
+            const metrics = computeMetrics(db, repoId);
+            const snapId = randomBytes(6).toString('hex'); // 12-char hex
+            const now = Date.now();
+            db.prepare(`
+        INSERT INTO snapshots (snapshot_id, repo_id, label, created_at, metrics)
+        VALUES (?, ?, ?, ?, ?)
+      `).run(snapId, repoId, label, now, JSON.stringify(metrics));
+            const record = {
+                snapshotId: snapId,
+                label,
+                createdAt: new Date(now).toISOString(),
+                fileCount: metrics.fileCount,
+                symbolCount: metrics.symbolCount,
+                edgeCount: metrics.edgeCount,
+                cycleCount: metrics.cycleCount,
+                avgCoupling: metrics.avgCoupling,
+                avgComplexity: metrics.avgComplexity,
+            };
+            const output = {
+                action: 'create',
+                snapshot: record,
+                _meta: buildMeta({ timingMs: Date.now() - t0 }),
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        }
+        if (action === 'list') {
+            const rows = db
+                .prepare('SELECT * FROM snapshots WHERE repo_id = ? ORDER BY created_at DESC')
+                .all(repoId);
+            const output = {
+                action: 'list',
+                snapshots: rows.map(rowToRecord),
+                _meta: buildMeta({ timingMs: Date.now() - t0 }),
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        }
+        if (action === 'diff') {
+            if (!snapshotId || !compareId) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: 'action "diff" requires both snapshotId (base) and compareId (compare).',
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const baseRow = db
+                .prepare('SELECT * FROM snapshots WHERE snapshot_id = ? AND repo_id = ?')
+                .get(snapshotId, repoId);
+            const compareRow = db
+                .prepare('SELECT * FROM snapshots WHERE snapshot_id = ? AND repo_id = ?')
+                .get(compareId, repoId);
+            if (!baseRow) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: `Snapshot "${snapshotId}" not found.` }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (!compareRow) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: `Snapshot "${compareId}" not found.` }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const baseMetrics = JSON.parse(baseRow.metrics);
+            const compareMetrics = JSON.parse(compareRow.metrics);
+            const baseFiles = new Set(baseMetrics.files);
+            const compareFiles = new Set(compareMetrics.files);
+            const filesAdded = compareMetrics.files.filter((f) => !baseFiles.has(f));
+            const filesRemoved = baseMetrics.files.filter((f) => !compareFiles.has(f));
+            const diff = {
+                filesAdded,
+                filesRemoved,
+                symbolsAdded: Math.max(0, compareMetrics.symbolCount - baseMetrics.symbolCount),
+                symbolsRemoved: Math.max(0, baseMetrics.symbolCount - compareMetrics.symbolCount),
+                edgesAdded: Math.max(0, compareMetrics.edgeCount - baseMetrics.edgeCount),
+                edgesRemoved: Math.max(0, baseMetrics.edgeCount - compareMetrics.edgeCount),
+                cycleCountDelta: compareMetrics.cycleCount - baseMetrics.cycleCount,
+                avgCouplingDelta: Math.round((compareMetrics.avgCoupling - baseMetrics.avgCoupling) * 100) / 100,
+                avgComplexityDelta: Math.round((compareMetrics.avgComplexity - baseMetrics.avgComplexity) * 100) / 100,
+            };
+            const output = {
+                action: 'diff',
+                snapshot: rowToRecord(baseRow),
+                diff,
+                _meta: buildMeta({ timingMs: Date.now() - t0 }),
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        }
+        if (action === 'delete') {
+            if (!snapshotId) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: 'action "delete" requires snapshotId.' }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const result = db
+                .prepare('DELETE FROM snapshots WHERE snapshot_id = ? AND repo_id = ?')
+                .run(snapshotId, repoId);
+            if (result.changes === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ error: `Snapshot "${snapshotId}" not found.` }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const output = {
+                action: 'delete',
+                _meta: buildMeta({ timingMs: Date.now() - t0 }),
+            };
+            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+        }
+        // Should never reach here (Zod enum validation prevents it)
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: `Unknown action: ${action}` }) }],
+            isError: true,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=get-architecture-snapshot.js.map