@luckychen1993/pm-mcp 0.1.1

package/dist/governance-tools.js

@@ -0,0 +1,240 @@
+import path from "node:path";
+import { z } from "zod";
+import { budgetLines, tool, toolW } from "./tool-base.js";
+import { foldLines } from "./budget.js";
+import { refreshDerived } from "./dashboard.js";
+import { requireInitialized } from "./paths.js";
+import { initGovernance, loadGovernance, saveGovernance, } from "./governance-model.js";
+import { auditGovernance } from "./governance-audit.js";
+import { impactAnalysis } from "./semantic-graph.js";
+import { assessQualityCoverage, createQualityPlan, discoverProjectUnits, runQualityPlan } from "./language-adapters.js";
+import { buildPortfolioFromRegistry, buildPortfolioReport, loadPortfolioProject } from "./portfolio.js";
+import { saveQualityRun } from "./quality-store.js";
+import { SemanticEvidenceDocumentSchema } from "./semantic-evidence.js";
+import { listSemanticEvidence, saveSemanticEvidence } from "./semantic-evidence-store.js";
+import { fingerprintProject } from "./project-fingerprint.js";
+const id = z.string().trim().min(1);
+const texts = z.array(z.string().trim().min(1));
+const moduleInput = {
+    id,
+    name: z.string().trim().min(1),
+    roots: texts.min(1),
+    kind: z.string().trim().min(1),
+    owners: texts,
+    languages: texts,
+    public_interfaces: texts.optional(),
+    depends_on: texts.optional(),
+    allowed_dependencies: texts.optional(),
+    denied_dependencies: texts.optional(),
+};
+function replaceById(items, value) {
+    const index = items.findIndex((item) => item.id === value.id);
+    if (index >= 0)
+        items[index] = value;
+    else
+        items.push(value);
+}
+function compactGovernance(governance) {
+    const lines = [
+        `治理 schema v${governance.schema_version}`,
+        `modules ${governance.modules.length} · interfaces ${governance.interfaces.length} · repositories ${governance.repositories.length}`,
+        `policies: ownership=${governance.policies.enforce_ownership} · declared=${governance.policies.enforce_declared_dependencies} · public=${governance.policies.enforce_public_interfaces} · unresolved=${governance.policies.fail_on_unresolved} · coverage>=${governance.policies.minimum_coverage_pct}% · semantic>=${governance.policies.minimum_semantic_assurance} · regex-fallback=${governance.policies.fail_on_semantic_fallback ? "forbidden" : "allowed"} · quality=${governance.policies.required_quality_kinds.join(",")}`,
+    ];
+    for (const module of governance.modules) {
+        lines.push(`- ${module.id} [${module.kind}] roots=${module.roots.join(",")} owners=${module.owners.join(",") || "无"} languages=${module.languages.join("+") || "无"} depends=${module.depends_on.join(",") || "无"}`);
+    }
+    for (const item of governance.interfaces)
+        lines.push(`- interface ${item.id} ${item.kind}@${item.version}: ${item.provider} -> ${item.consumers.join(",") || "无消费者"}`);
+    for (const repo of governance.repositories)
+        lines.push(`- repository ${repo.id}@${repo.version}: ${repo.root} -> ${repo.dependencies.map((dependency) => `${dependency.repository}@${dependency.constraint}`).join(",") || "无依赖"}`);
+    return foldLines(lines, { maxLines: 150, hint: "用 upsert_module/upsert_interface/upsert_repository 分项维护" });
+}
+function qualityPlan(root, unit, kinds) {
+    const units = discoverProjectUnits(root);
+    const coverage = assessQualityCoverage(units);
+    const selectedUnits = unit ? units.filter((item) => item.id === unit) : units;
+    if (unit && selectedUnits.length === 0)
+        throw new Error(`找不到质量单元 ${unit}。现有: ${units.map((item) => item.id).join(", ") || "无"}`);
+    let commands = createQualityPlan(selectedUnits);
+    if (kinds?.length)
+        commands = commands.filter((command) => kinds.includes(command.kind));
+    return { commands, coverage };
+}
+function qualityLines(commands) {
+    return commands.map((command, index) => `${index + 1}. [${command.kind}] (${command.cwd}) ${command.command} ${command.args.join(" ")}`);
+}
+export function registerGovernanceTools(server, root) {
+    tool(server, "init_governance", "为旧项目初始化 .pm/governance.json；新项目 init_project 已自动创建。", {}, () => {
+        requireInitialized(root);
+        const governance = initGovernance(root, {});
+        refreshDerived(root);
+        return `✅ 治理模型已初始化（schema v${governance.schema_version}）。下一步用 upsert_module 声明模块、owner 与语言。`;
+    });
+    tool(server, "get_governance", "查看结构化模块、owner、公开接口、仓库依赖与强制策略。", {}, () => {
+        requireInitialized(root);
+        return compactGovernance(loadGovernance(root));
+    });
+    toolW(server, root, "upsert_module", "新增或完整替换一个治理模块；root/owner/language/依赖边均经 schema 对账。", moduleInput, (args) => {
+        requireInitialized(root);
+        const governance = loadGovernance(root);
+        const value = {
+            ...args,
+            public_interfaces: args.public_interfaces ?? [],
+            depends_on: args.depends_on ?? [],
+            allowed_dependencies: args.allowed_dependencies ?? [],
+            denied_dependencies: args.denied_dependencies ?? [],
+        };
+        replaceById(governance.modules, value);
+        saveGovernance(root, governance);
+        refreshDerived(root);
+        return `✅ module ${value.id} 已保存（roots ${value.roots.length}，owners ${value.owners.length}，languages ${value.languages.length}）。`;
+    });
+    toolW(server, root, "upsert_interface", "新增或替换跨模块公开接口及契约文件、provider/consumers、版本。", {
+        id,
+        kind: z.string().trim().min(1),
+        provider: id,
+        consumers: texts,
+        contract_files: texts,
+        version: z.string().trim().min(1),
+    }, (args) => {
+        requireInitialized(root);
+        const governance = loadGovernance(root);
+        if (!governance.modules.some((module) => module.id === args.provider))
+            throw new Error(`provider module 不存在: ${args.provider}`);
+        for (const module of governance.modules)
+            module.public_interfaces = module.public_interfaces.filter((item) => item !== args.id);
+        governance.modules.find((module) => module.id === args.provider).public_interfaces.push(args.id);
+        replaceById(governance.interfaces, args);
+        saveGovernance(root, governance);
+        refreshDerived(root);
+        return `✅ interface ${args.id}@${args.version} 已保存：${args.provider} -> ${args.consumers.join(",") || "无消费者"}。`;
+    });
+    toolW(server, root, "upsert_repository", "登记当前组合视图中的仓库、版本及跨仓 semver 约束。", {
+        id,
+        name: z.string().trim().min(1),
+        root: z.string().trim().min(1),
+        version: z.string().trim().min(1),
+        dependencies: z.array(z.object({ repository: id, constraint: z.string().trim().min(1) })),
+    }, (args) => {
+        requireInitialized(root);
+        const governance = loadGovernance(root);
+        replaceById(governance.repositories, args);
+        saveGovernance(root, governance);
+        refreshDerived(root);
+        return `✅ repository ${args.id}@${args.version} 已保存（依赖 ${args.dependencies.length}）。`;
+    });
+    toolW(server, root, "set_governance_policies", "更新治理强制策略；未传字段保持原值。", {
+        enforce_ownership: z.boolean().optional(),
+        enforce_declared_dependencies: z.boolean().optional(),
+        fail_on_unresolved: z.boolean().optional(),
+        enforce_public_interfaces: z.boolean().optional(),
+        minimum_coverage_pct: z.number().min(0).max(100).optional(),
+        minimum_semantic_assurance: z.enum(["heuristic", "ast", "runtime"]).optional(),
+        fail_on_semantic_fallback: z.boolean().optional(),
+        required_quality_kinds: z.array(z.enum(["test", "build", "lint", "typecheck", "coverage", "security"])).optional(),
+    }, (args) => {
+        requireInitialized(root);
+        const governance = loadGovernance(root);
+        governance.policies = { ...governance.policies, ...args };
+        saveGovernance(root, governance);
+        refreshDerived(root);
+        return `✅ 治理策略已更新：coverage>=${governance.policies.minimum_coverage_pct}% · semantic>=${governance.policies.minimum_semantic_assurance} · regex-fallback=${governance.policies.fail_on_semantic_fallback ? "forbidden" : "allowed"}`;
+    });
+    tool(server, "discover_languages", "递归发现 Node/Python/Go/Rust/JVM/.NET 单元及其受控质量命令，不执行命令。", {}, () => {
+        requireInitialized(root);
+        const units = discoverProjectUnits(root);
+        const coverage = assessQualityCoverage(units);
+        const lines = [`发现 ${units.length} 个语言单元；质量命令覆盖 ${coverage.coveragePct}%（${coverage.unitsWithCommands}/${coverage.totalUnits}）`];
+        for (const unit of units)
+            lines.push(`- ${unit.id}: ${unit.languages.join("+") || "未知"} · manifests ${unit.manifest.map((item) => path.basename(item.path)).join(",")} · deps ${unit.dependencies.length} · dep-errors ${unit.dependencyErrors.length} · commands ${unit.qualityCommands.map((item) => item.kind).join(",") || "无"}`);
+        if (coverage.withoutCommands.length)
+            lines.push(`- 🚩 无质量命令: ${coverage.withoutCommands.join(", ")}`);
+        return foldLines(lines, { maxLines: budgetLines(root), hint: "按模块拆分治理 root" });
+    });
+    tool(server, "audit_governance", "审计跨文件/模块/语言语义覆盖、owner、公开接口、依赖边界、循环、unresolved 与质量矩阵覆盖。", {}, () => {
+        requireInitialized(root);
+        return auditGovernance(root, budgetLines(root)).report;
+    });
+    tool(server, "list_semantic_evidence", "列出已登记的语言原生 AST、编译器或运行时语义证据；损坏文档会使整次读取失败。", {}, () => {
+        requireInitialized(root);
+        return JSON.stringify(listSemanticEvidence(root), null, 2);
+    });
+    tool(server, "save_semantic_evidence", "保存一份绑定源码 SHA-256 的语言原生 AST/编译器/运行时证据；过期摘要在治理审计中严格失败。", {
+        id: z.string().trim().min(1).max(128),
+        document: SemanticEvidenceDocumentSchema,
+    }, (args) => {
+        requireInitialized(root);
+        const saved = saveSemanticEvidence(root, args.id, args.document);
+        return `✅ semantic evidence ${args.id} 已保存：${saved.file} · ${saved.analyzer.id} · ${saved.analyzer.assurance} · ${saved.status}`;
+    });
+    tool(server, "impact_analysis", "从变更文件沿 file/module 反向依赖闭包计算受影响文件与模块。", {
+        files: z.array(z.string().min(1)).min(1).max(100),
+    }, (args) => {
+        requireInitialized(root);
+        const audit = auditGovernance(root, budgetLines(root));
+        const impact = impactAnalysis(audit.graph, args.files);
+        return foldLines([
+            `变更 ${impact.changedFiles.length} · 受影响文件 ${impact.impactedFiles.length} · 模块 ${impact.impactedModules.length}`,
+            `模块: ${impact.impactedModules.join(", ") || "无"}`,
+            ...impact.dependentFiles.slice(0, 80).map((file) => `- ${file}`),
+            ...(impact.unknownChangedFiles.length ? [`⚠️ 未进入语义图: ${impact.unknownChangedFiles.join(", ")}`] : []),
+        ], { maxLines: budgetLines(root), hint: "缩小 files 输入或按模块运行" });
+    });
+    tool(server, "plan_quality_matrix", "生成跨语言真实质量命令计划；只规划，不启动进程。", {
+        unit: z.string().optional(),
+        kinds: z.array(z.enum(["test", "build", "lint", "typecheck", "coverage", "security"])).optional(),
+    }, (args) => {
+        requireInitialized(root);
+        const plan = qualityPlan(root, args.unit, args.kinds);
+        return foldLines([
+            `质量矩阵计划 ${plan.commands.length} 条；unit coverage ${plan.coverage.coveragePct}%（plan-only，未执行）`,
+            ...qualityLines(plan.commands),
+            ...(plan.coverage.withoutCommands.length ? [`🚩 无命令单元: ${plan.coverage.withoutCommands.join(", ")}`] : []),
+        ], { maxLines: budgetLines(root), hint: "用 unit/kinds 过滤；真实执行需 run_quality_matrix confirm_execute=true" });
+    });
+    tool(server, "run_quality_matrix", "显式执行跨语言质量矩阵。只运行受支持适配器生成的 argv，shell=false；缺工具/超时/非零均失败。", {
+        confirm_execute: z.literal(true).describe("必须显式为 true；该操作会运行目标项目构建/测试命令"),
+        unit: z.string().optional(),
+        kinds: z.array(z.enum(["test", "build", "lint", "typecheck", "coverage", "security"])).optional(),
+        stop_on_failure: z.boolean().optional(),
+    }, async (args) => {
+        requireInitialized(root);
+        if (args.confirm_execute !== true)
+            throw new Error("必须显式 confirm_execute=true");
+        const plan = qualityPlan(root, args.unit, args.kinds);
+        if (plan.coverage.withoutCommands.length)
+            throw new Error(`质量矩阵不完整，无命令单元: ${plan.coverage.withoutCommands.join(", ")}`);
+        if (plan.commands.length === 0)
+            throw new Error("质量矩阵为空，拒绝制造假绿");
+        const sourceBefore = fingerprintProject(root);
+        const executed = await runQualityPlan(plan.commands, { execute: true, stopOnFailure: args.stop_on_failure });
+        const sourceAfter = fingerprintProject(root);
+        const sourceStable = sourceBefore.sha256 === sourceAfter.sha256;
+        const result = { ...executed, ok: executed.ok && sourceStable };
+        const file = saveQualityRun(root, result, { source_before: sourceBefore, source_after: sourceAfter });
+        const lines = [`${result.ok ? "✅" : "🚩"} 质量矩阵 ${result.ok ? "通过" : "失败"}；结果 ${file}`];
+        if (!sourceStable)
+            lines.push(`- 🚩 源码在执行期间变化：before=${sourceBefore.sha256} after=${sourceAfter.sha256}`);
+        for (const item of result.results)
+            lines.push(`- [${item.status}] ${item.command.kind} ${item.command.cwd} (${item.durationMs}ms${item.exitCode === null ? "" : `, exit ${item.exitCode}`})`);
+        return foldLines(lines, { maxLines: budgetLines(root), hint: "查看 .pm/quality-runs 结构化摘要（不落原始输出）" });
+    });
+    tool(server, "get_portfolio", "聚合当前项目或全局注册项目的阶段、里程碑、债务、安全、语言、跨仓依赖/版本/cycle；加载失败不能假绿。", {
+        current_only: z.boolean().optional(),
+    }, (args) => {
+        requireInitialized(root);
+        const portfolio = args.current_only
+            ? buildPortfolioReport({ projects: [loadPortfolioProject(root)], projectsRequested: 1 })
+            : buildPortfolioFromRegistry();
+        const lines = [
+            `${portfolio.ok ? "✅" : "🚩"} portfolio projects ${portfolio.coverage.projects_loaded}/${portfolio.coverage.projects_requested} · failures ${portfolio.coverage.projects_failed} · repo edges ${portfolio.coverage.repository_dependencies} · violations ${portfolio.violations.length}`,
+        ];
+        for (const project of portfolio.projects)
+            lines.push(`- ${project.name}: ${project.phase || "无阶段"} · milestone active ${project.milestones.active}/${project.milestones.total} · debt ${project.tasks.debt_open} · security ${project.security.open} · languages ${project.languages.join("+") || "无"}`);
+        for (const violation of portfolio.violations.slice(0, 20))
+            lines.push(`- ${violation.severity === "error" ? "🚩" : "⚠️"} [${violation.code}] ${violation.message}`);
+        for (const failure of portfolio.projectFailures.slice(0, 10))
+            lines.push(`- 🚩 load ${failure.name}: ${failure.error}`);
+        return foldLines(lines, { maxLines: budgetLines(root), hint: "修复 projectFailures/跨仓版本或循环后重跑" });
+    });
+}

package/dist/health.js

@@ -0,0 +1,58 @@
+/** 距今天数 */
+export function ageDays(iso, nowMs = Date.now()) {
+    return Math.max(0, Math.floor((nowMs - Date.parse(iso)) / 86_400_000));
+}
+export function churnStats(sessions, threshold = 3, topN = 10) {
+    const counts = new Map();
+    for (const s of sessions) {
+        for (const f of s.files)
+            counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+    const hotspots = [...counts.entries()]
+        .filter(([, c]) => c >= threshold)
+        .map(([file, count]) => ({ file, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, topN);
+    return { hotspots, sessionCount: sessions.length };
+}
+export function debtAging(tasks, nowMs = Date.now()) {
+    const open = tasks.filter((t) => t.type === "debt" && t.status !== "done" && t.status !== "cancelled");
+    let oldestDays = 0;
+    let oldestTask = null;
+    for (const t of open) {
+        const d = ageDays(t.created, nowMs);
+        if (d > oldestDays) {
+            oldestDays = d;
+            oldestTask = `${t.id} ${t.title}`;
+        }
+    }
+    return { openDebt: open.length, oldestDays, oldestTask };
+}
+/* -------------------------------- 波及面告警 ------------------------------- */
+export function blastRadiusWarning(sessions, budgets) {
+    const last = sessions[sessions.length - 1];
+    if (!last)
+        return null;
+    if (last.files.length > budgets.sessionBlastRadius) {
+        return `最近一次会话波及 ${last.files.length} 个文件，超过阈值 ${budgets.sessionBlastRadius}——建议拆小任务或先立重构任务（散弹式修改嫌疑：${last.files.slice(0, 5).join(", ")}…）`;
+    }
+    return null;
+}
+export function footprint(sessions, tasks, nowMs = Date.now()) {
+    const recent = sessions.slice(-5).reverse();
+    const cutoff = nowMs - 30 * 86_400_000;
+    const completed30d = tasks.filter((t) => t.completed_at && Date.parse(t.completed_at) >= cutoff).length;
+    const avg = sessions.length === 0
+        ? 0
+        : Math.round((sessions.reduce((s, x) => s + x.files.length, 0) / sessions.length) * 10) / 10;
+    return {
+        recentSessions: recent.map((s) => ({
+            date: s.date.slice(0, 10),
+            author: s.author || "未知",
+            files: s.files.length,
+            summary: s.summary.length > 60 ? s.summary.slice(0, 60) + "…" : s.summary,
+        })),
+        tasksCompleted30d: completed30d,
+        avgFilesPerSession: avg,
+    };
+}

package/dist/index-db.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { pmPath } from "./paths.js";
+/** Low-level SQLite lifecycle, metadata, row iteration, and aggregate queries. */
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS files(
+  rel TEXT PRIMARY KEY,
+  top TEXT NOT NULL,
+  root1 TEXT NOT NULL,
+  dir TEXT NOT NULL,
+  ext TEXT NOT NULL,
+  is_test INTEGER NOT NULL,
+  is_lock INTEGER NOT NULL,
+  mtime REAL NOT NULL,
+  size INTEGER NOT NULL,
+  loc INTEGER NOT NULL DEFAULT 0,
+  skip INTEGER NOT NULL DEFAULT 0,
+  trivial INTEGER NOT NULL DEFAULT 0,
+  oversize INTEGER NOT NULL DEFAULT 0,
+  content_ok INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_files_top ON files(top);
+CREATE INDEX IF NOT EXISTS idx_files_root1 ON files(root1);
+CREATE TABLE IF NOT EXISTS meta(k TEXT PRIMARY KEY, v TEXT NOT NULL);
+`;
+const dbs = new Map();
+export function getIndex(root) {
+    const abs = path.resolve(root);
+    let db = dbs.get(abs);
+    if (db)
+        return db;
+    fs.mkdirSync(pmPath(abs), { recursive: true });
+    db = new DatabaseSync(pmPath(abs, "index.db"));
+    // journal_mode=WAL itself may need an exclusive lock. Configure the wait
+    // policy first so two MCP clients starting together do not race and crash.
+    db.exec("PRAGMA busy_timeout=8000");
+    db.exec("PRAGMA journal_mode=WAL");
+    db.exec("PRAGMA synchronous=NORMAL");
+    db.exec(SCHEMA);
+    dbs.set(abs, db);
+    return db;
+}
+/** 关闭并释放索引连接（Windows 上打开的 SQLite 文件无法被删除/移动） */
+export function closeIndex(root) {
+    const abs = path.resolve(root);
+    const db = dbs.get(abs);
+    if (db) {
+        try {
+            db.close();
+        }
+        catch {
+            /* ignore */
+        }
+        dbs.delete(abs);
+    }
+}
+export function getMeta(db, key) {
+    const row = db.prepare("SELECT v FROM meta WHERE k=?").get(key);
+    return row?.v ?? null;
+}
+export function setMeta(db, key, value) {
+    db.prepare("INSERT INTO meta(k,v) VALUES(?,?) ON CONFLICT(k) DO UPDATE SET v=excluded.v").run(key, value);
+}
+// Static SQL variants keep statements reusable and avoid dynamic SQL construction.
+const SQL_ROWS_ALL = "SELECT rel, ext, is_test, oversize FROM files WHERE is_lock=0 ORDER BY rel";
+const SQL_ROWS_NO_OVERSIZE = "SELECT rel, ext, is_test, oversize FROM files WHERE is_lock=0 AND oversize=0 ORDER BY rel";
+/** 流式遍历索引行（不整体物化；filter 缺省=全部非锁文件） */
+export function* iterateFileRows(db, filter = {}) {
+    const stmt = db.prepare(filter.excludeOversize ? SQL_ROWS_NO_OVERSIZE : SQL_ROWS_ALL);
+    for (const row of stmt.iterate()) {
+        if (filter.excludeTest && row.is_test === 1)
+            continue;
+        yield row;
+    }
+}
+export function aggregates(db) {
+    const one = (sql) => db.prepare(sql).get();
+    const total = one(`SELECT COUNT(*) c, COALESCE(SUM(CASE WHEN is_lock=0 THEN loc ELSE 0 END),0) loc FROM files`);
+    const test = one(`SELECT COUNT(*) c FROM files WHERE is_test=1`);
+    const skip = one(`SELECT COALESCE(SUM(skip),0) s FROM files`);
+    const contentOk = one(`SELECT COUNT(*) c FROM files WHERE content_ok=1`);
+    return {
+        totalFiles: total.c,
+        totalLoc: total.loc,
+        testFiles: test.c,
+        skipMarkers: skip.s,
+        trivialTests: db.prepare(`SELECT rel FROM files WHERE trivial=1 ORDER BY rel LIMIT 20`).all().map((r) => r.rel),
+        oversizeFiles: db.prepare(`SELECT rel FROM files WHERE oversize=1 ORDER BY rel LIMIT 20`).all().map((r) => r.rel),
+        largestFiles: db.prepare(`SELECT rel AS path, loc FROM files WHERE is_lock=0 ORDER BY loc DESC, rel LIMIT 10`).all(),
+        byExt: db.prepare(`SELECT ext, COUNT(*) files, COALESCE(SUM(loc),0) loc FROM files WHERE is_lock=0 GROUP BY ext ORDER BY loc DESC`).all(),
+        topDirs: db.prepare(`SELECT top AS dir, COUNT(*) files, COALESCE(SUM(loc),0) loc FROM files GROUP BY top ORDER BY loc DESC LIMIT 10`).all(),
+        rootDirs: db.prepare(`SELECT DISTINCT root1 FROM files`).all().map((r) => r.root1),
+        contentOk: contentOk.c,
+        indexCoverageBase: contentOk.c,
+    };
+}