feat: Pattern Momentum - detect migration direction via git history (v1.1.0)

Author: PatrickSys

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.1.0 (2025-12-15)
+
+### Features
+
+- **Pattern Momentum**: Detect migration direction via git history. Each pattern in `get_team_patterns` now includes:
+  - `newestFileDate`: ISO timestamp of the most recent file using this pattern
+  - `trend`: `Rising` (≤60 days), `Stable`, or `Declining` (≥180 days)
+- This solves the "3% Problem" — AI can now distinguish between legacy patterns being phased out vs. new patterns being adopted
+
+### Technical
+
+- New `src/utils/git-dates.ts`: Extracts file commit dates via single `git log` command
+- Updated `PatternDetector` to track temporal data per pattern
+- Graceful fallback for non-git repositories
+
 ## 1.0.1 (2025-12-11)
 
 ### Fixed

README.md

@@ -21,6 +21,7 @@ Add this to your MCP client config (Claude Desktop, VS Code, Cursor, etc.).
 
 - **Internal library discovery** → `@mycompany/ui-toolkit`: 847 uses vs `primeng`: 3 uses
 - **Pattern frequencies** → `inject()`: 97%, `constructor()`: 3%
+- **Pattern momentum** → `Signals`: Rising (last used 2 days ago) vs `RxJS`: Declining (180+ days)
 - **Golden file examples** → Real implementations showing all patterns together
 - **Testing conventions** → `Jest`: 74%, `Playwright`: 6%
 - **Framework patterns** → Angular signals, standalone components, etc.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-context",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "MCP server for semantic codebase indexing and search - gives AI agents real understanding of your codebase",
   "type": "module",
   "main": "./dist/lib.js",

src/core/indexer.ts

@@ -28,6 +28,7 @@ import {
   CodeChunkWithEmbedding,
 } from "../storage/index.js";
 import { LibraryUsageTracker, PatternDetector, ImportGraph } from "../utils/usage-tracker.js";
+import { getFileCommitDates } from "../utils/git-dates.js";
 
 export interface IndexerOptions {
   rootPath: string;
@@ -173,6 +174,9 @@ export class CodebaseIndexer {
       const patternDetector = new PatternDetector();
       const importGraph = new ImportGraph();
 
+      // Fetch git commit dates for pattern momentum analysis
+      const fileDates = await getFileCommitDates(this.rootPath);
+
       for (let i = 0; i < files.length; i++) {
         const file = files[i];
         this.progress.currentFile = file;
@@ -212,6 +216,11 @@ export class CodebaseIndexer {
 
             const relPath = file.split(/[\\/]/).slice(-3).join('/');
 
+            // Get file date for pattern momentum tracking
+            // Try multiple path formats since git uses forward slashes
+            const normalizedRelPath = path.relative(this.rootPath, file).replace(/\\/g, '/');
+            const fileDate = fileDates.get(normalizedRelPath);
+
             // GENERIC PATTERN FORWARDING
             // Framework analyzers return detectedPatterns in metadata - we just forward them
             // This keeps the indexer framework-agnostic
@@ -221,7 +230,7 @@ export class CodebaseIndexer {
                 const snippetPattern = this.getSnippetPatternFor(pattern.category, pattern.name);
                 const snippet = snippetPattern ? extractSnippet(snippetPattern) : undefined;
                 patternDetector.track(pattern.category, pattern.name,
-                  snippet ? { file: relPath, snippet } : undefined);
+                  snippet ? { file: relPath, snippet } : undefined, fileDate);
               }
             }
 

src/utils/git-dates.ts

@@ -0,0 +1,82 @@
+/**
+ * Git Date Utility
+ * Extracts file commit dates from git history for pattern momentum analysis
+ */
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import path from "path";
+
+const execAsync = promisify(exec);
+
+/**
+ * Get the last commit date for each file in the repository.
+ * Uses a single git command to efficiently extract all file dates.
+ * 
+ * @param rootPath - Root path of the git repository
+ * @returns Map of relative file paths to their last commit date
+ */
+export async function getFileCommitDates(rootPath: string): Promise<Map<string, Date>> {
+    const fileDates = new Map<string, Date>();
+
+    try {
+        // Single git command to get all file dates
+        // Format: ":::ISO_DATE" followed by affected files on new lines
+        const { stdout } = await execAsync(
+            'git log --format=":::%cd" --name-only --date=iso-strict',
+            {
+                cwd: rootPath,
+                maxBuffer: 50 * 1024 * 1024, // 50MB buffer for large repos
+            }
+        );
+
+        let currentDate: Date | null = null;
+
+        for (const line of stdout.split('\n')) {
+            const trimmed = line.trim();
+
+            if (!trimmed) continue;
+
+            if (trimmed.startsWith(':::')) {
+                // New commit date marker
+                const dateStr = trimmed.slice(3);
+                currentDate = new Date(dateStr);
+            } else if (currentDate) {
+                // File path - only store if we don't already have a date (first occurrence = most recent)
+                const normalizedPath = trimmed.replace(/\\/g, '/');
+                if (!fileDates.has(normalizedPath)) {
+                    fileDates.set(normalizedPath, currentDate);
+                }
+            }
+        }
+
+        console.error(`[git-dates] Loaded commit dates for ${fileDates.size} files`);
+    } catch (error) {
+        // Not a git repo or git not available - graceful fallback
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes('not a git repository') || message.includes('ENOENT')) {
+            console.error('[git-dates] Not a git repository, skipping temporal analysis');
+        } else {
+            console.error(`[git-dates] Failed to get git dates: ${message}`);
+        }
+    }
+
+    return fileDates;
+}
+
+/**
+ * Calculate pattern trend based on file date.
+ * 
+ * @param newestDate - The most recent file date using this pattern
+ * @returns Trend classification
+ */
+export function calculateTrend(newestDate: Date | undefined): 'Rising' | 'Declining' | 'Stable' | undefined {
+    if (!newestDate) return undefined;
+
+    const now = new Date();
+    const daysDiff = Math.floor((now.getTime() - newestDate.getTime()) / (1000 * 60 * 60 * 24));
+
+    if (daysDiff <= 60) return 'Rising';
+    if (daysDiff >= 180) return 'Declining';
+    return 'Stable';
+}

src/utils/usage-tracker.ts

@@ -10,6 +10,8 @@ export interface LibraryUsageStats {
   };
 }
 
+export type PatternTrend = 'Rising' | 'Declining' | 'Stable';
+
 export interface PatternUsageStats {
   [patternName: string]: {
     primary: {
@@ -18,11 +20,15 @@ export interface PatternUsageStats {
       frequency: string;
       examples: string[];
       canonicalExample?: { file: string; snippet: string };
+      newestFileDate?: string;
+      trend?: PatternTrend;
     };
     alsoDetected?: Array<{
       name: string;
       count: number;
       frequency: string;
+      newestFileDate?: string;
+      trend?: PatternTrend;
     }>;
   };
 }
@@ -212,24 +218,36 @@ const DEFAULT_TEST_FRAMEWORK_CONFIGS: TestFrameworkConfig[] = [
   { name: 'Generic Test', type: 'unit', indicators: ['describe(', 'it(', 'expect('], priority: 10 },
 ];
 
+import { calculateTrend } from "./git-dates.js";
+
 export class PatternDetector {
   private patterns: Map<string, Map<string, number>> = new Map();
   private canonicalExamples: Map<string, { file: string; snippet: string }> = new Map();
+  private patternFileDates: Map<string, Date> = new Map(); // Track newest file date per pattern
   private goldenFiles: GoldenFile[] = [];
   private testFrameworkConfigs: TestFrameworkConfig[];
 
   constructor(customConfigs?: TestFrameworkConfig[]) {
     this.testFrameworkConfigs = customConfigs || DEFAULT_TEST_FRAMEWORK_CONFIGS;
   }
 
-  track(category: string, patternName: string, example?: { file: string; snippet: string }): void {
+  track(category: string, patternName: string, example?: { file: string; snippet: string }, fileDate?: Date): void {
     if (!this.patterns.has(category)) {
       this.patterns.set(category, new Map());
     }
 
     const categoryPatterns = this.patterns.get(category)!;
     categoryPatterns.set(patternName, (categoryPatterns.get(patternName) || 0) + 1);
 
+    // Track newest file date for this pattern
+    if (fileDate) {
+      const dateKey = `${category}:${patternName}`;
+      const existing = this.patternFileDates.get(dateKey);
+      if (!existing || fileDate > existing) {
+        this.patternFileDates.set(dateKey, fileDate);
+      }
+    }
+
     // Smart Canonical Example Selection
     const exampleKey = `${category}:${patternName}`;
 
@@ -300,27 +318,41 @@ export class PatternDetector {
     const exampleKey = `${category}:${primaryName}`;
     const canonicalExample = this.canonicalExamples.get(exampleKey);
 
+    // Get temporal data for primary pattern
+    const primaryDate = this.patternFileDates.get(exampleKey);
+    const primaryTrend = calculateTrend(primaryDate);
+
     const result: PatternUsageStats[string] = {
       primary: {
         name: primaryName,
         count: primaryCount,
         frequency: `${primaryFreq}%`,
         examples: canonicalExample ? [canonicalExample.file] : [],
         canonicalExample: canonicalExample,
+        newestFileDate: primaryDate?.toISOString(),
+        trend: primaryTrend,
       },
     };
 
     if (sorted.length > 1) {
-      result.alsoDetected = sorted.slice(1, 3).map(([name, count]) => ({
-        name,
-        count,
-        frequency: `${Math.round((count / total) * 100)}%`,
-      }));
+      result.alsoDetected = sorted.slice(1, 3).map(([name, count]) => {
+        const altKey = `${category}:${name}`;
+        const altDate = this.patternFileDates.get(altKey);
+        const altTrend = calculateTrend(altDate);
+        return {
+          name,
+          count,
+          frequency: `${Math.round((count / total) * 100)}%`,
+          newestFileDate: altDate?.toISOString(),
+          trend: altTrend,
+        };
+      });
     }
 
     return result;
   }
 
+
   getAllPatterns(): PatternUsageStats {
     const stats: PatternUsageStats = {};