@apdesign/cursor-roi-tracker 0.5.2

package/README.md

@@ -0,0 +1,146 @@
+# cursor-roi-tracker
+
+`cursor-roi-tracker` 是一个面向 Git 提交的 AI 代码归因工具。  
+它会在 `pre-commit` 阶段统计本次暂存区代码变更与 AI 事件的交集，在 `post-commit` 阶段补齐提交信息、写入本地历史，并可选上报到服务端。
+
+## 功能概览
+
+- 自动安装 Git hooks（`pre-commit` / `post-commit`）
+- 基于暂存区 diff 做行级 AI 归因（新增/删除）
+- 提交后生成结构化报告（JSON/JSONL）
+- 支持消费并压缩已归因事件，减少事件文件膨胀
+- 可选静默换 token + 自动上报提交报告
+- 默认不阻塞开发流程（异常会记录到错误日志）
+
+## 安装
+
+在仓库根目录执行：
+
+```bash
+npm i -D cursor-roi-tracker
+```
+
+如果你发布的是带 scope 的包，也可以使用：
+
+```bash
+npm i -D @animus/cursor-roi-tracker
+```
+
+安装时会自动执行 `postinstall`，尝试完成以下动作：
+
+1. 写入/更新 `.git/hooks/pre-commit`
+2. 写入/更新 `.git/hooks/post-commit`
+3. 初始化默认配置文件 `.cursor-roi-tracker.json`（若不存在）
+4. 将事件文件加入 `.git/info/exclude`
+5. 若配置了服务端地址，尝试静默换取本地 token
+
+## 使用方法（推荐流程）
+
+### 第 1 步：安装 hooks（仅首次或需要重装时）
+
+```bash
+npx cursor-roi-install-hooks
+```
+
+> 若安装依赖后自动注入成功，这一步可跳过。
+
+### 第 2 步：正常开发并提交
+
+```bash
+git add .
+git commit -m "feat: your message"
+```
+
+提交时会自动触发：
+
+- `pre-commit`：采集当前暂存区指标，生成待提交报告
+- `post-commit`：绑定 commit sha/time，写入最终报告和历史
+
+### 第 3 步：查看本地产物
+
+默认写入在仓库的 `.cursor/` 下（若不可写则回退到 `.cursor-roi/`）：
+
+- `.cursor/ai-commit-report.pending.json`
+- `.cursor/ai-commit-report.final.json`
+- `.cursor/ai-commit-history.jsonl`
+- `.cursor/ai-commit-errors.jsonl`
+
+## 手动命令
+
+你也可以单独执行：
+
+```bash
+# 手动执行 pre-commit 采集
+npx cursor-roi-pre-commit
+
+# 手动执行 post-commit 绑定/压缩/上报
+npx cursor-roi-post-commit
+
+# 重新安装 hooks
+npx cursor-roi-install-hooks
+```
+
+## 配置说明
+
+配置文件名：`.cursor-roi-tracker.json`（仓库根目录）
+
+示例：
+
+```json
+{
+  "highThreshold": 0.85,
+  "sourceExtensions": [".ts", ".tsx", ".js", ".jsx", ".vue"],
+  "excludeRegexes": ["(^|/)dist/", "(^|/)build/", "\\.min\\."],
+  "eventsDirectory": [".cursor/animus-ai-events.jsonl", ".cursor/local-ai-events"],
+  "membersFile": ".cursor/enginuity_yunxiao_members.names.json",
+  "serverBaseUrl": "https://your-server.example.com",
+  "silentTokenPath": "/api/cursor-board/auth/silent-token",
+  "commitReportPath": "/api/cursor-board/commit-reports",
+  "requestTimeoutMs": 5000
+}
+```
+
+### 关键字段说明
+
+- `highThreshold`：判定 AI 归因命中阈值
+- `sourceExtensions`：参与统计的代码文件后缀
+- `excludeRegexes`：排除路径/文件规则（正则字符串）
+- `eventsDirectory`：AI 事件文件路径（支持多个）
+- `serverBaseUrl`：配置后启用提交后上报
+- `requestTimeoutMs`：服务端请求超时（毫秒）
+
+## 与服务端联动（可选）
+
+当 `serverBaseUrl` 已配置时：
+
+1. 安装 hooks 时会尝试调用 `silentTokenPath` 换取 token
+2. token 会写入 Git 目录下的本地文件（并自动加入 exclude）
+3. `post-commit` 会把最终报告 POST 到 `commitReportPath`
+
+如果未配置 `serverBaseUrl`，工具仍可完整执行本地统计，只是不进行网络上报。
+
+## 常见问题
+
+### 1) 为什么没有看到 AI 指标（全是 0）？
+
+优先检查：
+
+- `eventsDirectory` 指向的事件文件是否存在
+- 事件文件中是否有有效 `eventId`
+- 本次提交文件是否命中 `sourceExtensions` 且未被 `excludeRegexes` 排除
+
+### 2) 为什么没有生成报告文件？
+
+优先检查：
+
+- 是否在 Git 仓库内执行
+- hooks 是否成功写入 `.git/hooks/`
+- 是否真的有暂存区源代码文件参与提交
+
+### 3) 会不会阻塞提交？
+
+默认不会。命令失败会尽量记录到 `.cursor/ai-commit-errors.jsonl`，并避免中断主提交流程。
+
+## 许可证
+
+MIT

package/bin/install-hooks.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+const { runInstallHooks } = require('../src/cli-install-hooks');
+
+runInstallHooks().catch(() => {
+  process.exit(0);
+});

package/bin/post-commit.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+const { runPostCommit } = require('../src/cli-post-commit');
+
+runPostCommit().catch(() => {
+  process.exit(0);
+});

package/bin/pre-commit.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+const { runPreCommit } = require('../src/cli-pre-commit');
+
+runPreCommit().catch(() => {
+  process.exit(0);
+});

package/extension/extension.js

@@ -0,0 +1,244 @@
+const fs = require("fs");
+const path = require("path");
+const vscode = require("vscode");
+const crypto = require("crypto");
+const { acquireMutexLock, releaseMutexLock, resolveEventLockPath } = require("../src/mutex-lock");
+
+const EVENT_FILE_RELATIVE_PATH = path.join(".cursor", "animus-ai-events.jsonl");
+const BULK_INSERT_THRESHOLD = 15;
+const PURE_DELETE_THRESHOLD = 15;
+const DEBOUNCE_WINDOW_MS = 200;
+const NEARBY_LINE_DISTANCE = 8;
+const writeChainsByFile = new Map();
+const pendingDebounceByTarget = new Map();
+
+function activate(context) {
+  const subscription = vscode.workspace.onDidChangeTextDocument((event) => {
+    try {
+      handleDocumentChanged(event);
+    } catch (_error) {
+      // Keep extension silent in background mode.
+    }
+  });
+
+  context.subscriptions.push(subscription);
+}
+
+function deactivate() {
+  for (const key of Array.from(pendingDebounceByTarget.keys())) {
+    const pending = pendingDebounceByTarget.get(key);
+    if (pending?.timer) {
+      clearTimeout(pending.timer);
+    }
+    flushPendingEvent(key);
+  }
+}
+
+function handleDocumentChanged(event) {
+  const document = event?.document;
+  if (!document || document.uri.scheme !== "file") {
+    return;
+  }
+  if (isUndoOrRedo(event.reason)) {
+    return;
+  }
+
+  const workspaceFolder = vscode.workspace.getWorkspaceFolder(document.uri);
+  if (!workspaceFolder) {
+    return;
+  }
+
+  for (const change of event.contentChanges || []) {
+    if (!change) {
+      continue;
+    }
+    const insertLines = countInsertedLines(change.text);
+    // Important: deleted lines must use line coordinates, never rangeLength (characters).
+    const deletedLines = Math.max(0, change.range.end.line - change.range.start.line);
+    const replacedLines = Math.max(1, deletedLines + 1);
+    if (isFullFileReplacement(change, document.lineCount, replacedLines)) {
+      continue;
+    }
+
+    const relativePath = normalizeRelativePath(
+      path.relative(workspaceFolder.uri.fsPath, document.uri.fsPath)
+    );
+    if (!relativePath || relativePath.startsWith("..")) {
+      continue;
+    }
+
+    const eventFilePath = path.join(workspaceFolder.uri.fsPath, EVENT_FILE_RELATIVE_PATH);
+    const payloads = buildEventPayloads({
+      change,
+      relativePath,
+      insertLines,
+      deletedLines,
+    });
+    for (const payload of payloads) {
+      enqueueDebouncedEvent(eventFilePath, payload);
+    }
+  }
+}
+
+function normalizeRelativePath(inputPath) {
+  return String(inputPath || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.\//, "")
+    .trim();
+}
+
+function isUndoOrRedo(reason) {
+  return (
+    reason === vscode.TextDocumentChangeReason.Undo ||
+    reason === vscode.TextDocumentChangeReason.Redo
+  );
+}
+
+function countInsertedLines(text) {
+  if (text === "") {
+    return 0;
+  }
+  const normalizedText = String(text || "").replace(/\r\n/g, "\n");
+  return normalizedText.split("\n").length;
+}
+
+function isFullFileReplacement(change, fileLineCount, replacedLines) {
+  const startsAtTop = change.range.start.line === 0 && change.range.start.character === 0;
+  const nearWholeFile = replacedLines >= Math.max(1, fileLineCount - 1);
+  return startsAtTop && nearWholeFile;
+}
+
+function enqueueJsonlAppend(filePath, payload) {
+  const line = `${JSON.stringify(payload)}\n`;
+  const prev = writeChainsByFile.get(filePath) || Promise.resolve();
+  const next = prev
+    .catch(() => undefined)
+    .then(async () => {
+      await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+      const repoRoot = resolveRepoRootFromEventFile(filePath);
+      const lockHandle = await acquireMutexLock(resolveEventLockPath(repoRoot));
+      try {
+        await fs.promises.appendFile(filePath, line, "utf8");
+      } finally {
+        await releaseMutexLock(lockHandle);
+      }
+    })
+    .catch(() => undefined);
+  writeChainsByFile.set(filePath, next);
+}
+
+function buildEventPayloads({ change, relativePath, insertLines, deletedLines }) {
+  const payloads = [];
+  const now = Date.now();
+  const insertStartLine = change.range.start.line + 1;
+  const insertEndLine = insertLines > 0 ? insertStartLine + insertLines - 1 : null;
+  const deleteStartLine = change.range.start.line + 1;
+  const deleteEndLine = deletedLines > 0 ? deleteStartLine + deletedLines - 1 : null;
+
+  if (insertLines > BULK_INSERT_THRESHOLD) {
+    payloads.push({
+      eventId: crypto.randomUUID(),
+      type: "agent_bulk_insert",
+      file_path: relativePath,
+      insert_lines: insertLines,
+      deleted_lines: deletedLines,
+      insert_start_line: insertStartLine,
+      insert_end_line: insertEndLine,
+      delete_start_line: deleteStartLine,
+      delete_end_line: deleteEndLine,
+      timestamp: now,
+    });
+  }
+
+  if (insertLines === 0 && deletedLines > PURE_DELETE_THRESHOLD) {
+    payloads.push({
+      eventId: crypto.randomUUID(),
+      type: "agent_pure_delete",
+      file_path: relativePath,
+      insert_lines: 0,
+      deleted_lines: deletedLines,
+      delete_start_line: deleteStartLine,
+      delete_end_line: deleteEndLine,
+      timestamp: now,
+    });
+  }
+
+  return payloads;
+}
+
+function resolveRepoRootFromEventFile(filePath) {
+  return path.dirname(path.dirname(filePath));
+}
+
+function enqueueDebouncedEvent(eventFilePath, payload) {
+  const filePath = normalizeRelativePath(payload.file_path);
+  const key = `${eventFilePath}::${filePath}`;
+  const current = pendingDebounceByTarget.get(key);
+
+  if (!current) {
+    pendingDebounceByTarget.set(key, createPendingEntry(key, eventFilePath, payload));
+    return;
+  }
+
+  if (isNearbyPayload(current.payload, payload)) {
+    clearTimeout(current.timer);
+    current.payload = payload;
+    current.timer = setTimeout(() => flushPendingEvent(key), DEBOUNCE_WINDOW_MS);
+    return;
+  }
+
+  clearTimeout(current.timer);
+  flushPendingEvent(key);
+  pendingDebounceByTarget.set(key, createPendingEntry(key, eventFilePath, payload));
+}
+
+function createPendingEntry(key, eventFilePath, payload) {
+  return {
+    eventFilePath,
+    payload,
+    timer: setTimeout(() => flushPendingEvent(key), DEBOUNCE_WINDOW_MS),
+  };
+}
+
+function flushPendingEvent(key) {
+  const pending = pendingDebounceByTarget.get(key);
+  if (!pending) {
+    return;
+  }
+  pendingDebounceByTarget.delete(key);
+  enqueueJsonlAppend(pending.eventFilePath, pending.payload);
+}
+
+function isNearbyPayload(prevPayload, nextPayload) {
+  if (!prevPayload || !nextPayload) {
+    return false;
+  }
+  const prevPath = normalizeRelativePath(prevPayload.file_path);
+  const nextPath = normalizeRelativePath(nextPayload.file_path);
+  if (!prevPath || !nextPath || prevPath !== nextPath) {
+    return false;
+  }
+  const prevLine = getPrimaryLineForPayload(prevPayload);
+  const nextLine = getPrimaryLineForPayload(nextPayload);
+  if (!Number.isFinite(prevLine) || !Number.isFinite(nextLine)) {
+    return false;
+  }
+  return Math.abs(prevLine - nextLine) <= NEARBY_LINE_DISTANCE;
+}
+
+function getPrimaryLineForPayload(payload) {
+  const deleteStart = Number(payload.delete_start_line);
+  if (Number.isFinite(deleteStart)) {
+    return deleteStart;
+  }
+  const insertStart = Number(payload.insert_start_line);
+  if (Number.isFinite(insertStart)) {
+    return insertStart;
+  }
+  return Number(payload.start_line);
+}
+
+module.exports = {
+  activate,
+  deactivate,
+};

package/extension/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "animus-cursor-roi-tracker",
+  "displayName": "Animus Cursor ROI Tracker",
+  "description": "Silently captures bulk agent insert events for ROI attribution.",
+  "version": "0.1.0",
+  "publisher": "animus",
+  "engines": {
+    "vscode": "^1.74.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "activationEvents": [
+    "onStartupFinished"
+  ],
+  "main": "./extension.js"
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@apdesign/cursor-roi-tracker",
+  "version": "0.5.2",
+  "description": "Collect commit-level AI coding metrics from staged diff and local AI events",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "bin": {
+    "cursor-roi-pre-commit": "./bin/pre-commit.js",
+    "cursor-roi-post-commit": "./bin/post-commit.js",
+    "cursor-roi-install-hooks": "./bin/install-hooks.js"
+  },
+  "scripts": {
+    "postinstall": "node ./bin/install-hooks.js --auto",
+    "precommit:collect": "node ./bin/pre-commit.js",
+    "postcommit:collect": "node ./bin/post-commit.js",
+    "hooks:install": "node ./bin/install-hooks.js",
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "extension",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}