feat(metrics): add code_metadata table and MetricsStore methods

prosdev · prosdev · commit 2ee6ad9065c7 · 2025-12-12T19:21:14.000-08:00
Phase 2.1: Code Metadata Schema &amp; Store Methods

Database Schema:
- Added code_metadata table with foreign key to snapshots
- Stores per-file metrics: commit_count, author_count, LOC, functions, imports
- Includes calculated risk_score for hotspot detection
- Indexes for efficient querying (by snapshot, risk, file)
- CASCADE DELETE when snapshots are removed

Types &amp; Schemas:
- Added CodeMetadata interface with Zod schema
- Added CodeMetadataQuery for filtering/sorting
- Added Hotspot interface for analysis results
- Exported all new types from metrics module

MetricsStore Methods:
- appendCodeMetadata() - Bulk insert with transaction
- getCodeMetadata() - Query with filtering and sorting
- getCodeMetadataForFile() - File history across snapshots
- getCodeMetadataCount() - Count records per snapshot
- calculateRiskScore() - Risk formula: (commits * LOC) / authors

Risk Score Formula:
- High commits = frequently changed (more bugs)
- High LOC = more complex (harder to maintain)
- Low authors = knowledge concentrated (bus factor)

Next: Analytics module and CLI integration
diff --git a/packages/core/src/metrics/index.ts b/packages/core/src/metrics/index.ts
@@ -7,11 +7,16 @@
 export { initializeDatabase, METRICS_SCHEMA_V1 } from './schema.js';
 export { MetricsStore } from './store.js';
 export type {
+  CodeMetadata,
+  CodeMetadataQuery,
+  Hotspot,
   MetricsConfig,
   Snapshot,
   SnapshotQuery,
 } from './types.js';
 export {
+  CodeMetadataSchema,
   DEFAULT_METRICS_CONFIG,
+  HotspotSchema,
   SnapshotQuerySchema,
 } from './types.js';
diff --git a/packages/core/src/metrics/schema.ts b/packages/core/src/metrics/schema.ts
@@ -44,6 +44,39 @@ export const METRICS_SCHEMA_V1 = `
   -- Index for filtering by trigger type
   CREATE INDEX IF NOT EXISTS idx_snapshots_trigger 
     ON snapshots(trigger, timestamp DESC);
+
+  -- Code metadata table (per-file metrics for hotspot detection)
+  CREATE TABLE IF NOT EXISTS code_metadata (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    snapshot_id TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    
+    -- Data we have or can easily get:
+    commit_count INTEGER,           -- From change frequency
+    last_modified INTEGER,          -- From change frequency (timestamp)
+    author_count INTEGER,           -- From change frequency
+    lines_of_code INTEGER,          -- Count lines during scan
+    num_functions INTEGER,          -- From document count
+    num_imports INTEGER,            -- From DocumentMetadata.imports
+    
+    -- Calculated risk score
+    risk_score REAL,                -- (commit_count * lines_of_code) / max(author_count, 1)
+    
+    FOREIGN KEY (snapshot_id) REFERENCES snapshots(id) ON DELETE CASCADE,
+    UNIQUE (snapshot_id, file_path)
+  );
+
+  -- Index for querying by snapshot
+  CREATE INDEX IF NOT EXISTS idx_code_metadata_snapshot 
+    ON code_metadata(snapshot_id);
+    
+  -- Index for finding hotspots (highest risk files)
+  CREATE INDEX IF NOT EXISTS idx_code_metadata_risk 
+    ON code_metadata(risk_score DESC);
+    
+  -- Index for file-specific queries
+  CREATE INDEX IF NOT EXISTS idx_code_metadata_file 
+    ON code_metadata(file_path);
 `;
 
 /**
diff --git a/packages/core/src/metrics/store.ts b/packages/core/src/metrics/store.ts
@@ -10,7 +10,13 @@ import type { Logger } from '@lytics/kero';
 import Database from 'better-sqlite3';
 import type { DetailedIndexStats } from '../indexer/types.js';
 import { initializeDatabase } from './schema.js';
-import { type Snapshot, type SnapshotQuery, SnapshotQuerySchema } from './types.js';
+import {
+  type CodeMetadata,
+  type CodeMetadataQuery,
+  type Snapshot,
+  type SnapshotQuery,
+  SnapshotQuerySchema,
+} from './types.js';
 
 /**
  * Metrics Store Class
@@ -223,6 +229,178 @@ export class MetricsStore {
     return result.changes;
   }
 
+  /**
+   * Calculate risk score for a file
+   * Formula: (commit_count * lines_of_code) / max(author_count, 1)
+   *
+   * Rationale:
+   * - High commit count = frequently changed (more bugs)
+   * - High LOC = more complex (harder to maintain)
+   * - Low author count = knowledge concentrated (bus factor risk)
+   */
+  private calculateRiskScore(metadata: CodeMetadata): number {
+    const commitCount = metadata.commitCount || 0;
+    const authorCount = Math.max(metadata.authorCount || 1, 1);
+    const linesOfCode = metadata.linesOfCode;
+
+    return (commitCount * linesOfCode) / authorCount;
+  }
+
+  /**
+   * Append code metadata for a snapshot
+   *
+   * @param snapshotId - Snapshot ID to associate metadata with
+   * @param metadata - Array of file metadata to store
+   * @returns Number of records inserted
+   */
+  appendCodeMetadata(snapshotId: string, metadata: CodeMetadata[]): number {
+    if (metadata.length === 0) return 0;
+
+    const stmt = this.db.prepare(`
+      INSERT INTO code_metadata 
+      (snapshot_id, file_path, commit_count, last_modified, author_count, 
+       lines_of_code, num_functions, num_imports, risk_score)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    const insert = this.db.transaction((items: CodeMetadata[]) => {
+      for (const item of items) {
+        const riskScore = this.calculateRiskScore(item);
+        stmt.run(
+          snapshotId,
+          item.filePath,
+          item.commitCount || null,
+          item.lastModified ? item.lastModified.getTime() : null,
+          item.authorCount || null,
+          item.linesOfCode,
+          item.numFunctions,
+          item.numImports,
+          riskScore
+        );
+      }
+    });
+
+    try {
+      insert(metadata);
+      this.logger?.debug({ snapshotId, count: metadata.length }, 'Appended code metadata');
+      return metadata.length;
+    } catch (error) {
+      this.logger?.error({ error, snapshotId }, 'Failed to append code metadata');
+      throw error;
+    }
+  }
+
+  /**
+   * Get code metadata for a snapshot
+   *
+   * @param query - Query parameters
+   * @returns Array of code metadata
+   */
+  getCodeMetadata(query: CodeMetadataQuery): CodeMetadata[] {
+    let sql = 'SELECT * FROM code_metadata WHERE snapshot_id = ?';
+    const params: unknown[] = [query.snapshotId];
+
+    if (query.minRiskScore !== undefined) {
+      sql += ' AND risk_score >= ?';
+      params.push(query.minRiskScore);
+    }
+
+    // Sort order
+    const sortBy = query.sortBy || 'risk_desc';
+    switch (sortBy) {
+      case 'risk_desc':
+        sql += ' ORDER BY risk_score DESC';
+        break;
+      case 'risk_asc':
+        sql += ' ORDER BY risk_score ASC';
+        break;
+      case 'lines_desc':
+        sql += ' ORDER BY lines_of_code DESC';
+        break;
+      case 'commits_desc':
+        sql += ' ORDER BY commit_count DESC';
+        break;
+    }
+
+    sql += ' LIMIT ?';
+    params.push(query.limit || 100);
+
+    const rows = this.db.prepare(sql).all(...params) as Array<{
+      file_path: string;
+      commit_count: number | null;
+      last_modified: number | null;
+      author_count: number | null;
+      lines_of_code: number;
+      num_functions: number;
+      num_imports: number;
+      risk_score: number;
+    }>;
+
+    return rows.map((row) => ({
+      filePath: row.file_path,
+      commitCount: row.commit_count || undefined,
+      lastModified: row.last_modified ? new Date(row.last_modified) : undefined,
+      authorCount: row.author_count || undefined,
+      linesOfCode: row.lines_of_code,
+      numFunctions: row.num_functions,
+      numImports: row.num_imports,
+      riskScore: row.risk_score,
+    }));
+  }
+
+  /**
+   * Get code metadata for a specific file across snapshots
+   *
+   * @param filePath - File path to query
+   * @param limit - Maximum number of snapshots to return (default: 10)
+   * @returns Array of code metadata ordered by snapshot timestamp (newest first)
+   */
+  getCodeMetadataForFile(filePath: string, limit = 10): CodeMetadata[] {
+    const sql = `
+      SELECT cm.*, s.timestamp 
+      FROM code_metadata cm
+      JOIN snapshots s ON cm.snapshot_id = s.id
+      WHERE cm.file_path = ?
+      ORDER BY s.timestamp DESC
+      LIMIT ?
+    `;
+
+    const rows = this.db.prepare(sql).all(filePath, limit) as Array<{
+      file_path: string;
+      commit_count: number | null;
+      last_modified: number | null;
+      author_count: number | null;
+      lines_of_code: number;
+      num_functions: number;
+      num_imports: number;
+      risk_score: number;
+    }>;
+
+    return rows.map((row) => ({
+      filePath: row.file_path,
+      commitCount: row.commit_count || undefined,
+      lastModified: row.last_modified ? new Date(row.last_modified) : undefined,
+      authorCount: row.author_count || undefined,
+      linesOfCode: row.lines_of_code,
+      numFunctions: row.num_functions,
+      numImports: row.num_imports,
+      riskScore: row.risk_score,
+    }));
+  }
+
+  /**
+   * Get count of code metadata records for a snapshot
+   *
+   * @param snapshotId - Snapshot ID
+   * @returns Total number of code metadata records
+   */
+  getCodeMetadataCount(snapshotId: string): number {
+    const result = this.db
+      .prepare('SELECT COUNT(*) as count FROM code_metadata WHERE snapshot_id = ?')
+      .get(snapshotId) as { count: number };
+    return result.count;
+  }
+
   /**
    * Close the database connection
    */
diff --git a/packages/core/src/metrics/types.ts b/packages/core/src/metrics/types.ts
@@ -71,3 +71,76 @@ export const DEFAULT_METRICS_CONFIG: Required<MetricsConfig> = {
   retentionDays: 90,
   maxSizeMB: 100,
 };
+
+/**
+ * Per-file code metadata for hotspot detection
+ */
+export interface CodeMetadata {
+  filePath: string;
+  commitCount?: number;
+  lastModified?: Date;
+  authorCount?: number;
+  linesOfCode: number;
+  numFunctions: number;
+  numImports: number;
+  riskScore?: number;
+}
+
+/**
+ * Zod schema for code metadata
+ */
+export const CodeMetadataSchema = z.object({
+  filePath: z.string().min(1),
+  commitCount: z.number().int().nonnegative().optional(),
+  lastModified: z.coerce.date().optional(),
+  authorCount: z.number().int().positive().optional(),
+  linesOfCode: z.number().int().nonnegative(),
+  numFunctions: z.number().int().nonnegative(),
+  numImports: z.number().int().nonnegative(),
+  riskScore: z.number().nonnegative().optional(),
+});
+
+/**
+ * Query parameters for retrieving code metadata
+ */
+export interface CodeMetadataQuery {
+  /** Snapshot ID to query */
+  snapshotId: string;
+
+  /** Minimum risk score threshold */
+  minRiskScore?: number;
+
+  /** Maximum number of results (default: 100) */
+  limit?: number;
+
+  /** Sort order (default: 'risk_desc') */
+  sortBy?: 'risk_desc' | 'risk_asc' | 'lines_desc' | 'commits_desc';
+}
+
+/**
+ * Hotspot detection result
+ */
+export interface Hotspot {
+  filePath: string;
+  riskScore: number;
+  commitCount: number;
+  authorCount: number;
+  linesOfCode: number;
+  numFunctions: number;
+  lastModified?: Date;
+  reason: string; // Human-readable explanation
+}
+
+/**
+ * Zod schema for hotspot results
+ */
+export const HotspotSchema = z.object({
+  filePath: z.string(),
+  riskScore: z.number().nonnegative(),
+  commitCount: z.number().int().nonnegative(),
+  authorCount: z.number().int().positive(),
+  linesOfCode: z.number().int().nonnegative(),
+  numFunctions: z.number().int().nonnegative(),
+  lastModified: z.coerce.date().optional(),
+  reason: z.string(),
+});
