@jussmor/commit-memory-mcp 0.3.7 → 0.3.8

package/README.md

@@ -108,6 +108,9 @@ build_context_pack({
 ```
 
 Use this before invoking a coding subagent to keep prompts small and focused.
+If no rows are found in strict scope, the server now falls back automatically to broader scope levels.
+
+Important: if you provide `domain`/`feature`/`branch` tags in `build_context_pack`, use the same tags during `sync_pr_context` for best precision.
 
 ### Promote draft facts after review
 
@@ -143,6 +146,20 @@ who_changed_this({
 
 Use this to discover recent authors and commit history for a target file.
 
+### Explain what is happening in a Next.js folder
+
+```text
+explain_path_activity({
+  targetPath: "app/dashboard",
+  owner: "MaxwellClinic-Development",
+  repo: "EverBetter-Pro",
+  limit: 30
+})
+```
+
+Use this when you want a fast folder-level summary for areas like `app/dashboard`, `app/(authenticated)`, or `src/components`.
+It returns recent commits, top authors, most touched files, and related PR context/decisions when available.
+
 ### Explain intent for a change
 
 ```text

package/dist/db/client.js

@@ -371,32 +371,30 @@ export function promoteContextFacts(db, options) {
     return Number(result.changes ?? 0);
 }
 export function buildContextPack(db, options) {
-    const clauses = [];
-    const params = [];
-    if (options.domain) {
-        clauses.push("scope_domain = ?");
-        params.push(options.domain);
-    }
-    if (options.feature) {
-        clauses.push("scope_feature = ?");
-        params.push(options.feature);
-    }
-    if (options.branch) {
-        clauses.push("scope_branch = ?");
-        params.push(options.branch);
-    }
-    if (options.taskType) {
-        clauses.push("scope_task_type IN (?, 'general')");
-        params.push(options.taskType);
-    }
-    if (options.includeDraft) {
-        clauses.push("status IN ('promoted', 'draft')");
-    }
-    else {
-        clauses.push("status = 'promoted'");
-    }
-    const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
-    const sql = `
+    const taskType = options.taskType ?? "general";
+    function runQuery(params) {
+        const clauses = [];
+        const values = [taskType, taskType];
+        if (params.includeDomain && options.domain) {
+            clauses.push("scope_domain = ?");
+            values.push(options.domain);
+        }
+        if (params.includeFeature && options.feature) {
+            clauses.push("scope_feature = ?");
+            values.push(options.feature);
+        }
+        if (params.includeBranch && options.branch) {
+            clauses.push("scope_branch = ?");
+            values.push(options.branch);
+        }
+        if (options.includeDraft) {
+            clauses.push("status IN ('promoted', 'draft')");
+        }
+        else {
+            clauses.push("status = 'promoted'");
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+        const sql = `
     SELECT
       id,
       source_type,
@@ -411,10 +409,15 @@ export function buildContextPack(db, options) {
       confidence,
       status,
       updated_at,
-      ((priority * 0.45) + (confidence * 0.35) +
+      ((priority * 0.40) + (confidence * 0.30) +
         CASE
-          WHEN scope_task_type = ? THEN 0.20
-          WHEN scope_task_type = 'general' THEN 0.10
+          WHEN scope_task_type = ? THEN 0.30
+          WHEN scope_task_type = 'general' THEN 0.15
+          ELSE 0.0
+        END +
+        CASE
+          WHEN source_type = 'pr_description' THEN 0.15
+          WHEN source_type LIKE 'pr_%' THEN 0.08
           ELSE 0.0
         END) AS score
     FROM context_facts
@@ -422,24 +425,46 @@ export function buildContextPack(db, options) {
     ORDER BY score DESC, updated_at DESC
     LIMIT ?
   `;
-    const taskType = options.taskType ?? "general";
-    const rows = db.prepare(sql).all(taskType, ...params, options.limit);
-    return rows.map((row) => ({
-        id: String(row.id ?? ""),
-        sourceType: String(row.source_type ?? ""),
-        sourceRef: String(row.source_ref ?? ""),
-        title: String(row.title ?? ""),
-        content: String(row.content ?? ""),
-        domain: String(row.scope_domain ?? ""),
-        feature: String(row.scope_feature ?? ""),
-        branch: String(row.scope_branch ?? ""),
-        taskType: String(row.scope_task_type ?? ""),
-        priority: Number(row.priority ?? 0),
-        confidence: Number(row.confidence ?? 0),
-        score: Number(row.score ?? 0),
-        status: String(row.status ?? "promoted"),
-        updatedAt: String(row.updated_at ?? ""),
-    }));
+        values.push(options.limit);
+        const rows = db.prepare(sql).all(...values);
+        return rows.map((row) => ({
+            id: String(row.id ?? ""),
+            sourceType: String(row.source_type ?? ""),
+            sourceRef: String(row.source_ref ?? ""),
+            title: String(row.title ?? ""),
+            content: String(row.content ?? ""),
+            domain: String(row.scope_domain ?? ""),
+            feature: String(row.scope_feature ?? ""),
+            branch: String(row.scope_branch ?? ""),
+            taskType: String(row.scope_task_type ?? ""),
+            priority: Number(row.priority ?? 0),
+            confidence: Number(row.confidence ?? 0),
+            score: Number(row.score ?? 0),
+            status: String(row.status ?? "promoted"),
+            updatedAt: String(row.updated_at ?? ""),
+        }));
+    }
+    const strictRows = runQuery({
+        includeDomain: true,
+        includeFeature: true,
+        includeBranch: true,
+    });
+    if (strictRows.length > 0) {
+        return strictRows;
+    }
+    const broadRows = runQuery({
+        includeDomain: true,
+        includeFeature: false,
+        includeBranch: false,
+    });
+    if (broadRows.length > 0) {
+        return broadRows;
+    }
+    return runQuery({
+        includeDomain: false,
+        includeFeature: false,
+        includeBranch: false,
+    });
 }
 export function archiveFeatureContext(db, options) {
     const now = new Date().toISOString();

package/dist/git/insights.d.ts

@@ -16,6 +16,27 @@ export declare function whoChangedFile(options: {
         lastCommitAt: string;
     }>;
 };
+export declare function explainPathActivity(options: {
+    repoPath: string;
+    targetPath: string;
+    limit: number;
+}): {
+    targetPath: string;
+    commits: Array<{
+        sha: string;
+        author: string;
+        date: string;
+        subject: string;
+    }>;
+    topAuthors: Array<{
+        author: string;
+        commitCount: number;
+    }>;
+    topFiles: Array<{
+        filePath: string;
+        touchCount: number;
+    }>;
+};
 export declare function latestCommitForFile(repoPath: string, filePath: string): string | null;
 export declare function commitDetails(repoPath: string, sha: string): {
     sha: string;

package/dist/git/insights.js

@@ -46,6 +46,66 @@ export function whoChangedFile(options) {
         authors,
     };
 }
+export function explainPathActivity(options) {
+    const repoPath = path.resolve(options.repoPath);
+    const limit = Math.max(1, options.limit);
+    const targetPath = options.targetPath.trim();
+    const commitsRaw = runGit(repoPath, [
+        "log",
+        `-n${limit}`,
+        "--format=%H%x1f%an%x1f%aI%x1f%s",
+        "--",
+        targetPath,
+    ]).trim();
+    if (!commitsRaw) {
+        return {
+            targetPath,
+            commits: [],
+            topAuthors: [],
+            topFiles: [],
+        };
+    }
+    const commits = commitsRaw.split("\n").map((line) => {
+        const [sha = "", author = "", date = "", subject = ""] = line.split("\x1f");
+        return { sha, author, date, subject };
+    });
+    const authorCounts = new Map();
+    const fileCounts = new Map();
+    for (const commit of commits) {
+        authorCounts.set(commit.author, (authorCounts.get(commit.author) ?? 0) + 1);
+        const filesRaw = runGit(repoPath, [
+            "show",
+            "--name-only",
+            "--pretty=format:",
+            commit.sha,
+            "--",
+            targetPath,
+        ]).trim();
+        if (!filesRaw) {
+            continue;
+        }
+        for (const filePath of filesRaw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)) {
+            fileCounts.set(filePath, (fileCounts.get(filePath) ?? 0) + 1);
+        }
+    }
+    const topAuthors = Array.from(authorCounts.entries())
+        .map(([author, commitCount]) => ({ author, commitCount }))
+        .sort((a, b) => b.commitCount - a.commitCount)
+        .slice(0, 8);
+    const topFiles = Array.from(fileCounts.entries())
+        .map(([filePath, touchCount]) => ({ filePath, touchCount }))
+        .sort((a, b) => b.touchCount - a.touchCount)
+        .slice(0, 12);
+    return {
+        targetPath,
+        commits,
+        topAuthors,
+        topFiles,
+    };
+}
 export function latestCommitForFile(repoPath, filePath) {
     const output = runGit(path.resolve(repoPath), [
         "log",

package/dist/mcp/server.js

@@ -7,7 +7,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { archiveFeatureContext, buildContextPack, openDatabase, promoteContextFacts, upsertWorktreeSession, } from "../db/client.js";
-import { commitDetails, latestCommitForFile, mainBranchOvernightBrief, resumeFeatureSessionBrief, whoChangedFile, } from "../git/insights.js";
+import { commitDetails, explainPathActivity, latestCommitForFile, mainBranchOvernightBrief, resumeFeatureSessionBrief, whoChangedFile, } from "../git/insights.js";
 import { listActiveWorktrees } from "../git/worktree.js";
 import { syncPullRequestContext } from "../pr/sync.js";
 function fetchRemote(repoPath) {
@@ -26,6 +26,78 @@ function detectReferencedPrNumber(text) {
     }
     return value;
 }
+function parsePrNumberFromSourceRef(sourceRef) {
+    const match = sourceRef.match(/#(\d{1,8})\b/);
+    if (!match) {
+        return null;
+    }
+    const value = Number.parseInt(match[1] ?? "", 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        return null;
+    }
+    return value;
+}
+function loadPathPullRequestContext(db, options) {
+    const prNumbers = new Set(options.referencedPrNumbers);
+    const likePattern = `%${options.targetPath}%`;
+    const sourceRows = db
+        .prepare(`
+      SELECT source_ref
+      FROM context_facts
+      WHERE (title LIKE ? OR content LIKE ?)
+        AND source_ref LIKE '%#%'
+      ORDER BY updated_at DESC
+      LIMIT 80
+    `)
+        .all(likePattern, likePattern);
+    for (const row of sourceRows) {
+        const number = parsePrNumberFromSourceRef(String(row.source_ref ?? ""));
+        if (number) {
+            prNumbers.add(number);
+        }
+    }
+    if (prNumbers.size === 0) {
+        return [];
+    }
+    const results = [];
+    for (const prNumber of Array.from(prNumbers).slice(0, 20)) {
+        const pr = options.owner && options.repo
+            ? (db
+                .prepare(`
+              SELECT repo_owner, repo_name, pr_number, title, body, author, state, created_at, updated_at, merged_at, url
+              FROM prs
+              WHERE repo_owner = ? AND repo_name = ? AND pr_number = ?
+              LIMIT 1
+            `)
+                .get(options.owner, options.repo, prNumber) ?? null)
+            : (db
+                .prepare(`
+              SELECT repo_owner, repo_name, pr_number, title, body, author, state, created_at, updated_at, merged_at, url
+              FROM prs
+              WHERE pr_number = ?
+              ORDER BY updated_at DESC
+              LIMIT 1
+            `)
+                .get(prNumber) ?? null);
+        if (!pr) {
+            continue;
+        }
+        const decisions = db
+            .prepare(`
+        SELECT id, source, author, summary, severity, created_at
+        FROM pr_decisions
+        WHERE repo_owner = ? AND repo_name = ? AND pr_number = ?
+        ORDER BY created_at DESC
+        LIMIT 20
+      `)
+            .all(pr.repo_owner, pr.repo_name, pr.pr_number);
+        results.push({
+            pr,
+            decisions,
+        });
+    }
+    return results;
+}
 function loadPullRequestContext(db, prNumber, repoOwner, repoName) {
     const pr = repoOwner && repoName
         ? (db
@@ -162,6 +234,20 @@ export async function startMcpServer() {
                     required: ["filePath"],
                 },
             },
+            {
+                name: "explain_path_activity",
+                description: "Given a file or folder path, summarize activity, top files/authors, and related PR context.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        targetPath: { type: "string" },
+                        owner: { type: "string" },
+                        repo: { type: "string" },
+                        limit: { type: "number" },
+                    },
+                    required: ["targetPath"],
+                },
+            },
             {
                 name: "why_was_this_changed",
                 description: "Explain intent for a commit or file using git history and synced PR decisions.",
@@ -376,6 +462,52 @@ export async function startMcpServer() {
                 content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
             };
         }
+        if (request.params.name === "explain_path_activity") {
+            const targetPath = String(request.params.arguments?.targetPath ?? "").trim();
+            const owner = String(request.params.arguments?.owner ?? "").trim();
+            const repo = String(request.params.arguments?.repo ?? "").trim();
+            const limit = Number(request.params.arguments?.limit ?? 25);
+            if (!targetPath) {
+                return {
+                    content: [{ type: "text", text: "targetPath is required" }],
+                    isError: true,
+                };
+            }
+            const output = explainPathActivity({
+                repoPath,
+                targetPath,
+                limit: Number.isFinite(limit) && limit > 0 ? limit : 25,
+            });
+            const referencedPrNumbers = output.commits
+                .map((commit) => {
+                const details = commitDetails(repoPath, commit.sha);
+                return detectReferencedPrNumber(`${details.subject}\n${details.body}`);
+            })
+                .filter((value) => Number.isFinite(value));
+            const db = openDatabase(dbPath);
+            try {
+                const relatedPullRequests = loadPathPullRequestContext(db, {
+                    targetPath,
+                    owner: owner || undefined,
+                    repo: repo || undefined,
+                    referencedPrNumbers,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ...output,
+                                relatedPullRequests,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            finally {
+                db.close();
+            }
+        }
         if (request.params.name === "why_was_this_changed") {
             const owner = String(request.params.arguments?.owner ?? "").trim();
             const repo = String(request.params.arguments?.repo ?? "").trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jussmor/commit-memory-mcp",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "mcpName": "io.github.jussmor/commit-memory",
   "description": "Commit-aware RAG with sqlite-vec and MCP tools for local agent workflows",
   "license": "MIT",