@luckychen1993/pm-mcp 0.1.1

package/dist/security.js

@@ -0,0 +1,269 @@
+import { createHash } from "node:crypto";
+import { loadExtraRules, loadProject, loadSecurity, saveSecurity } from "./store.js";
+import { latestSnapshot } from "./audit.js";
+import { readDirectDeps } from "./scan.js";
+import { ensureFresh, getIndex, iterateFileRows } from "./index-store.js";
+import { readText } from "./search.js";
+import { now } from "./types.js";
+const SECRET_PATTERNS = [
+    { id: "secret.aws-access-key", severity: "high", pattern: /AKIA[0-9A-Z]{16}/, message: "疑似 AWS Access Key" },
+    { id: "secret.github-token", severity: "high", pattern: /gh[pousr]_[A-Za-z0-9]{20,}/, message: "疑似 GitHub Token" },
+    { id: "secret.openai-key", severity: "high", pattern: /sk-[A-Za-z0-9_-]{24,}/, message: "疑似 OpenAI/兼容平台 API Key" },
+    { id: "secret.google-api", severity: "high", pattern: /AIza[0-9A-Za-z_-]{35}/, message: "疑似 Google API Key" },
+    { id: "secret.slack-token", severity: "high", pattern: /xox[baprs]-[0-9A-Za-z-]{10,}/, message: "疑似 Slack Token" },
+    {
+        id: "secret.private-key",
+        severity: "high",
+        pattern: /-----BEGIN (RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----/,
+        message: "内联私钥",
+    },
+    {
+        id: "secret.generic-assignment",
+        severity: "medium",
+        pattern: /\b(api[_-]?key|apikey|secret|token|password|passwd)\b\s*[:=]\s*["'][^"'\s]{10,}["']/i,
+        message: "疑似硬编码凭据赋值",
+    },
+];
+const DANGEROUS_PATTERNS = [
+    { id: "danger.eval", severity: "medium", pattern: /\beval\s*\(/, message: "eval() 动态执行（注入风险）", glob: /\.(js|ts|mjs|cjs|jsx|tsx)$/ },
+    { id: "danger.new-function", severity: "medium", pattern: /new\s+Function\s*\(/, message: "new Function() 动态执行", glob: /\.(js|ts|mjs|cjs|jsx|tsx)$/ },
+    { id: "danger.exec-sync", severity: "medium", pattern: /exec(ution)?Sync\s*\(/, message: "execSync 同步执行命令", glob: /\.(js|ts|mjs|cjs|jsx|tsx)$/ },
+    { id: "danger.tls-disabled", severity: "high", pattern: /rejectUnauthorized\s*:\s*false|NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*["']?0/, message: "禁用 TLS 证书校验", glob: /\.(js|ts|mjs|cjs|jsx|tsx)$/ },
+    { id: "danger.cors-wildcard", severity: "medium", pattern: /cors\s*\(\s*\{\s*origin\s*:\s*["']\*["']/, message: "CORS 通配放开", glob: /\.(js|ts|mjs|cjs|jsx|tsx)$/ },
+    { id: "danger.sql-concat", severity: "high", pattern: /(select|insert\s+into|update|delete\s+from)\b[^;"'`]*("\s*\+|'\s*\+|\$\{|%\s*\(|f")/i, message: "SQL 与字符串拼接/插值（注入风险）", glob: /\.(js|ts|mjs|cjs|jsx|tsx|py)$/ },
+    { id: "danger.innerhtml", severity: "medium", pattern: /\.innerHTML\s*=|document\.write\s*\(/, message: "直接写 innerHTML（XSS 风险）", glob: /\.(js|ts|mjs|cjs|jsx|tsx)$/ },
+    { id: "danger.python-exec", severity: "medium", pattern: /\beval\s*\(|\bexec\s*\(/, message: "Python eval/exec 动态执行", glob: /\.py$/ },
+    { id: "danger.python-shell-true", severity: "high", pattern: /shell\s*=\s*True/, message: "subprocess shell=True（注入风险）", glob: /\.py$/ },
+    { id: "danger.python-pickle", severity: "medium", pattern: /pickle\.loads?\s*\(|yaml\.load\s*\((?![^)]*Loader)/, message: "不安全反序列化（pickle/yaml.load）", glob: /\.py$/ },
+    { id: "danger.python-tls-off", severity: "high", pattern: /verify\s*=\s*False|CERT_NONE/, message: "禁用 TLS 证书校验", glob: /\.py$/ },
+    { id: "danger.flask-debug", severity: "low", pattern: /app\.run\s*\([^)]*debug\s*=\s*True/, message: "Flask 生产开启 debug", glob: /\.py$/ },
+];
+/** 占位符判定：避免把示例/模板值当泄露 */
+function looksPlaceholder(value) {
+    return /process\.env|os\.environ|\$\{|<[^>]+>|^\$\{|xxx|your[_-]|example|sample|template|changeme|change_me|placeholder|\{\{/i.test(value);
+}
+function shouldIgnoreSecretMatch(rule, matched) {
+    return rule.id === "secret.generic-assignment" && looksPlaceholder(matched);
+}
+function findRelevantMatch(rule, value) {
+    const flags = rule.pattern.flags.includes("g") ? rule.pattern.flags : `${rule.pattern.flags}g`;
+    const pattern = new RegExp(rule.pattern.source, flags);
+    for (const match of value.matchAll(pattern)) {
+        if (shouldIgnoreSecretMatch(rule, match[0]))
+            continue;
+        return match;
+    }
+    return undefined;
+}
+/**
+ * 处置理由与代码扫描共用同一套内置秘密规则，避免新增规则后 note 校验漏防。
+ * 占位符沿用扫描口径，允许说明已脱敏的示例值。
+ */
+function findSecretRule(value) {
+    for (const rule of SECRET_PATTERNS) {
+        if (findRelevantMatch(rule, value))
+            return rule;
+    }
+    return undefined;
+}
+function fingerprint(ruleId, rel, matched) {
+    return createHash("sha1").update(ruleId + "|" + rel + "|" + matched).digest("hex").slice(0, 16);
+}
+function scanDetections(root) {
+    const out = [];
+    const rules = [...SECRET_PATTERNS, ...DANGEROUS_PATTERNS];
+    // 用户自定义规则
+    for (const r of loadExtraRules(root).rules) {
+        try {
+            rules.push({
+                id: r.id,
+                severity: r.severity,
+                pattern: new RegExp(r.pattern, "i"),
+                message: r.message || `自定义规则 ${r.id}`,
+                glob: r.glob ? new RegExp(r.glob) : undefined,
+            });
+        }
+        catch {
+            /* 非法自定义规则跳过 */
+        }
+    }
+    ensureFresh(root);
+    const db = getIndex(root);
+    // .env 类文件存在性检查（是否被 git 提交需人工确认）
+    for (const row of iterateFileRows(db, { excludeOversize: false })) {
+        const base = row.rel.split("/").pop() ?? "";
+        if (/^\.env(\.[^./]+)?$/.test(base) && !/example|sample|template/i.test(base)) {
+            out.push({
+                rule: "secret.env-file",
+                severity: "medium",
+                file: row.rel,
+                line: 1,
+                fingerprint: fingerprint("secret.env-file", row.rel, base),
+                message: "存在 .env 类文件——确认未被提交且已在 .gitignore",
+            });
+        }
+    }
+    for (const row of iterateFileRows(db)) {
+        const rel = row.rel;
+        if (row.oversize === 1)
+            continue;
+        if (rel.startsWith(".pm/"))
+            continue;
+        const content = readText(root, rel);
+        if (content === null)
+            continue;
+        const lines = content.split("\n");
+        for (const rule of rules) {
+            if (rule.glob && !rule.glob.test(rel))
+                continue;
+            for (let i = 0; i < lines.length; i++) {
+                const m = findRelevantMatch(rule, lines[i]);
+                if (!m)
+                    continue;
+                const matched = m[0];
+                out.push({
+                    rule: rule.id,
+                    severity: rule.severity,
+                    file: rel,
+                    line: i + 1,
+                    fingerprint: fingerprint(rule.id, rel, matched),
+                    message: rule.message,
+                });
+            }
+        }
+    }
+    return out;
+}
+/** 扫描并更新台账（幂等：重复扫描不产生重复条目） */
+export function auditSecurity(root) {
+    const project = loadProject(root);
+    const stamp = now();
+    const detections = scanDetections(root);
+    const security = loadSecurity(root);
+    const existing = new Map(security.findings.map((f) => [f.fingerprint, f]));
+    const acceptedRefound = [];
+    const seen = new Set();
+    let seq = security.findings.reduce((m, f) => {
+        const n = Number(f.id.replace("SEC-", ""));
+        return Math.max(m, n);
+    }, 0);
+    for (const d of detections) {
+        seen.add(d.fingerprint);
+        const old = existing.get(d.fingerprint);
+        if (old) {
+            old.last_seen = stamp;
+            // 钻空子防线：标了 fixed 却又检出 → 重开（fixed 不是免死金牌）
+            if (old.status === "fixed") {
+                old.status = "open";
+                old.note += "（自动：曾标记 fixed 但再次检出，已重开）";
+            }
+            else if (old.status === "accepted") {
+                acceptedRefound.push(old);
+            }
+        }
+        else {
+            seq += 1;
+            security.findings.push({
+                id: `SEC-${String(seq).padStart(3, "0")}`,
+                rule: d.rule,
+                severity: d.severity,
+                file: d.file,
+                line: d.line,
+                fingerprint: d.fingerprint,
+                status: "open",
+                note: d.message,
+                first_seen: stamp,
+                last_seen: stamp,
+            });
+        }
+    }
+    // 不再检出且仍 open 的 → 自动转 fixed（附注说明）
+    let autoFixed = 0;
+    for (const f of security.findings) {
+        if (f.status === "open" && !seen.has(f.fingerprint)) {
+            f.status = "fixed";
+            f.note += "（自动：最近一次扫描未再检出）";
+            autoFixed += 1;
+        }
+    }
+    security.last_scan = stamp;
+    saveSecurity(root, security);
+    // 依赖风险（新增依赖 + 幻觉易发版本号）
+    const { depSpecs } = readDirectDeps(root);
+    const prev = latestSnapshot(root);
+    const prevDeps = prev?.deps ?? [];
+    const newDeps = prev ? depSpecs.map((d) => d.name).filter((n) => !prevDeps.includes(n)) : [];
+    const riskyDeps = depSpecs.filter((d) => d.risky).map((d) => `${d.name}@${d.version}`);
+    const fresh = security.findings.filter((f) => f.first_seen === stamp && f.status === "open");
+    const open = security.findings.filter((f) => f.status === "open");
+    const high = open.filter((f) => f.severity === "high");
+    const L = [];
+    L.push(`## 安全体检报告（exposure=${project.exposure}）`);
+    // exposure 兑现：不同暴露面使用不同处置口径
+    if (project.exposure === "public") {
+        const mustFix = open.filter((f) => f.severity === "high" || f.severity === "medium");
+        L.push(`🚨 项目面向公网：中危及以上均须处置。需处置 ${mustFix.length} 个（高危 ${high.length}，中危 ${open.filter((f) => f.severity === "medium").length}；低危可带理由接受）。`);
+    }
+    else if (project.exposure === "network") {
+        L.push(`项目面向网络：高危须处置。未处理 ${open.length} 个（高危 ${high.length}，中危 ${open.filter((f) => f.severity === "medium").length}，低危 ${open.filter((f) => f.severity === "low").length}）。`);
+    }
+    else {
+        L.push(open.length === 0
+            ? "✅ 当前无未处理安全发现（本地工具：低危可带理由接受）。"
+            : `未处理发现 ${open.length} 个（高危 ${high.length}，中危 ${open.filter((f) => f.severity === "medium").length}，低危 ${open.filter((f) => f.severity === "low").length}）。`);
+    }
+    if (fresh.length > 0) {
+        L.push("");
+        L.push(`本次扫描新发现 ${fresh.length} 个:`);
+        for (const f of fresh.slice(0, 15)) {
+            L.push(`- [${f.severity.toUpperCase()}] ${f.file}:${f.line} ${f.rule} — ${f.note}`);
+        }
+    }
+    if (acceptedRefound.length > 0) {
+        L.push("");
+        L.push(`⚠️ 已接受的风险再次检出 ${acceptedRefound.length} 个（接受≠永久免疫，请复核）:`);
+        for (const f of acceptedRefound.slice(0, 10)) {
+            L.push(`- ${f.id} ${f.file}:${f.line} ${f.rule}`);
+        }
+    }
+    if (autoFixed > 0)
+        L.push(`自动关闭 ${autoFixed} 个（代码中已不再出现）。`);
+    if (newDeps.length > 0)
+        L.push(`⚠️ 上次快照后新增依赖: ${newDeps.join(", ")}（AI 引入的依赖请审查来源与必要性）`);
+    if (riskyDeps.length > 0)
+        L.push(`⚠️ 幻觉易发版本号（* / latest）: ${riskyDeps.join(", ")}`);
+    L.push("");
+    L.push("处理方式：修复后重扫自动关闭；`resolve_finding` 可带理由接受风险（accepted 必须留 note）。");
+    return {
+        newFindings: fresh.length,
+        openCount: open.length,
+        highCount: high.length,
+        autoFixed,
+        newDeps,
+        riskyDeps,
+        text: L,
+    };
+}
+export function listFindings(root, status) {
+    const all = loadSecurity(root).findings;
+    return status ? all.filter((f) => f.status === status) : all;
+}
+export function resolveFinding(root, id, status, note) {
+    const security = loadSecurity(root);
+    const f = security.findings.find((x) => x.id === id);
+    if (!f)
+        throw new Error(`找不到安全发现 ${id}，用 list_findings 查看现有条目。`);
+    const cleanNote = note.trim();
+    if (status === "accepted" && !cleanNote) {
+        throw new Error("接受风险必须填写理由（note）：接受是显式选择，要留痕。");
+    }
+    const secretRule = findSecretRule(cleanNote);
+    if (secretRule) {
+        throw new Error(`note 不得包含密钥形态明文（命中 ${secretRule.id}）——描述风险时引用位置与规则即可，绝不复述凭据本身。`);
+    }
+    f.status = status;
+    if (cleanNote)
+        f.note = cleanNote;
+    saveSecurity(root, security);
+    return f;
+}

package/dist/semantic-evidence-store.js

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pmPath } from "./paths.js";
+import { atomicWrite, withLedgerLock } from "./store.js";
+import { SemanticEvidenceDocumentSchema } from "./semantic-evidence.js";
+export const SEMANTIC_EVIDENCE_DIR = "semantic-evidence";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i;
+export function validateSemanticEvidenceId(id) {
+    if (id !== id.trim() || !SAFE_ID.test(id) || id.endsWith(".") || WINDOWS_DEVICE.test(id)) {
+        throw new Error(`非法语义证据 ID: ${JSON.stringify(id)}；仅允许 1-128 位 ASCII 字母、数字、点、下划线和连字符，且不得使用路径或 Windows 设备名`);
+    }
+    return id;
+}
+export function semanticEvidenceDir(root) {
+    return pmPath(path.resolve(root), SEMANTIC_EVIDENCE_DIR);
+}
+function isWithin(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function assertRealDirectoryWithinRoot(root, directory, create) {
+    const absoluteRoot = path.resolve(root);
+    if (!fs.existsSync(absoluteRoot) || !fs.statSync(absoluteRoot).isDirectory())
+        throw new Error(`项目根目录不存在或不是目录: ${absoluteRoot}`);
+    if (create)
+        fs.mkdirSync(directory, { recursive: true });
+    if (!fs.existsSync(directory))
+        return;
+    const realRoot = fs.realpathSync.native(absoluteRoot);
+    const realDirectory = fs.realpathSync.native(directory);
+    if (!isWithin(realRoot, realDirectory))
+        throw new Error(`语义证据目录逃逸项目根目录: ${directory}`);
+}
+export function semanticEvidencePath(root, id) {
+    const safeId = validateSemanticEvidenceId(id);
+    const directory = semanticEvidenceDir(root);
+    const file = path.resolve(directory, `${safeId}.json`);
+    if (!isWithin(path.resolve(directory), file))
+        throw new Error(`语义证据路径逃逸: ${id}`);
+    return file;
+}
+function parseDocument(file) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`语义证据 JSON 解析失败: ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const parsed = SemanticEvidenceDocumentSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`语义证据 schema 校验失败: ${file}: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`).join("; ")}`);
+    }
+    return parsed.data;
+}
+function assertRegularEvidenceFile(root, file) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`语义证据必须是普通文件，拒绝符号链接或目录: ${file}`);
+    const realRoot = fs.realpathSync.native(path.resolve(root));
+    const realFile = fs.realpathSync.native(file);
+    if (!isWithin(realRoot, realFile))
+        throw new Error(`语义证据文件逃逸项目根目录: ${file}`);
+}
+function evidenceIdsUnlocked(root) {
+    const directory = semanticEvidenceDir(root);
+    assertRealDirectoryWithinRoot(root, directory, false);
+    if (!fs.existsSync(directory))
+        return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.name.endsWith(".json"))
+        .map((entry) => {
+        if (!entry.isFile() || entry.isSymbolicLink())
+            throw new Error(`语义证据目录包含非普通 JSON 文件: ${entry.name}`);
+        return validateSemanticEvidenceId(entry.name.slice(0, -".json".length));
+    })
+        .sort((a, b) => a.localeCompare(b));
+}
+function loadUnlocked(root, id) {
+    const file = semanticEvidencePath(root, id);
+    const directory = semanticEvidenceDir(root);
+    assertRealDirectoryWithinRoot(root, directory, false);
+    if (!fs.existsSync(file))
+        throw new Error(`语义证据不存在: ${id}`);
+    assertRegularEvidenceFile(root, file);
+    return parseDocument(file);
+}
+/** Validate first, then atomically replace one evidence document under the project ledger lock. */
+export function saveSemanticEvidence(root, id, input) {
+    const safeId = validateSemanticEvidenceId(id);
+    const parsed = SemanticEvidenceDocumentSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`语义证据 schema 校验失败: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`).join("; ")}`);
+    }
+    const absoluteRoot = path.resolve(root);
+    const directory = semanticEvidenceDir(absoluteRoot);
+    assertRealDirectoryWithinRoot(absoluteRoot, directory, true);
+    return withLedgerLock(absoluteRoot, () => {
+        assertRealDirectoryWithinRoot(absoluteRoot, directory, false);
+        atomicWrite(semanticEvidencePath(absoluteRoot, safeId), `${JSON.stringify(parsed.data, null, 2)}\n`);
+        return parsed.data;
+    });
+}
+export function loadSemanticEvidence(root, id) {
+    return loadUnlocked(path.resolve(root), validateSemanticEvidenceId(id));
+}
+/** List is schema-validating: a corrupt document makes the operation fail closed. */
+export function listSemanticEvidence(root) {
+    const absoluteRoot = path.resolve(root);
+    return evidenceIdsUnlocked(absoluteRoot).map((id) => {
+        const document = loadUnlocked(absoluteRoot, id);
+        return {
+            id,
+            file: document.file,
+            language: document.language,
+            analyzer: document.analyzer.id,
+            assurance: document.analyzer.assurance,
+            status: document.status,
+            generated_at: document.generated_at,
+            content_sha256: document.content_sha256,
+        };
+    });
+}
+/** Load a consistent, validated snapshot; no corrupt document is silently skipped. */
+export function loadAllSemanticEvidence(root) {
+    const absoluteRoot = path.resolve(root);
+    const directory = semanticEvidenceDir(absoluteRoot);
+    assertRealDirectoryWithinRoot(absoluteRoot, directory, false);
+    if (!fs.existsSync(directory))
+        return [];
+    return withLedgerLock(absoluteRoot, () => evidenceIdsUnlocked(absoluteRoot).map((id) => loadUnlocked(absoluteRoot, id)));
+}

package/dist/semantic-evidence.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const SEMANTIC_EVIDENCE_SCHEMA_VERSION = 1;
+export const SemanticAssuranceSchema = z.enum(["heuristic", "ast", "runtime"]);
+export const SemanticAnalyzerFamilySchema = z.enum([
+    "compiler-ast",
+    "language-native-ast",
+    "structured-parser",
+    "runtime-trace",
+    "regex-fallback",
+]);
+export const SemanticCapabilitySchema = z.enum(["imports", "exports", "calls", "contracts", "http", "grpc", "ffi"]);
+export const SemanticReferenceKindSchema = z.enum(["import", "export", "call", "contract", "http", "grpc", "ffi"]);
+export const AnalyzerProvenanceSchema = z.object({
+    id: z.string().trim().min(1),
+    family: SemanticAnalyzerFamilySchema,
+    assurance: SemanticAssuranceSchema,
+    engine: z.string().trim().min(1),
+    version: z.string().trim().min(1),
+    capabilities: z.array(SemanticCapabilitySchema).min(1),
+    /** Optional reproducibility detail. It must never contain source text or credentials. */
+    command: z.string().trim().min(1).optional(),
+}).superRefine((analyzer, ctx) => {
+    const expected = analyzer.family === "runtime-trace"
+        ? "runtime"
+        : analyzer.family === "regex-fallback"
+            ? "heuristic"
+            : "ast";
+    if (analyzer.assurance !== expected) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["assurance"], message: `${analyzer.family} requires assurance=${expected}` });
+    }
+});
+const EvidenceReferenceSchema = z.object({
+    kind: SemanticReferenceKindSchema,
+    specifier: z.string().trim().min(1),
+    line: z.number().int().positive(),
+    confidence: z.number().min(0).max(1),
+    force_local: z.boolean().default(false),
+    symbol: z.string().trim().min(1).optional(),
+});
+const EvidenceExportSchema = z.object({
+    name: z.string().trim().min(1),
+    line: z.number().int().positive(),
+    is_type_only: z.boolean().default(false),
+    source_specifier: z.string().trim().min(1).optional(),
+    confidence: z.number().min(0).max(1),
+});
+/**
+ * Portable interchange format for compiler/native-AST analyzers and runtime tracers.
+ * A content hash binds every claim to the exact source bytes that were analyzed.
+ */
+export const SemanticEvidenceDocumentSchema = z.object({
+    schema_version: z.literal(SEMANTIC_EVIDENCE_SCHEMA_VERSION),
+    file: z.string().trim().min(1),
+    language: z.string().trim().min(1),
+    content_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    generated_at: z.string().datetime({ offset: true }),
+    status: z.enum(["complete", "partial"]),
+    analyzer: AnalyzerProvenanceSchema,
+    references: z.array(EvidenceReferenceSchema).default([]),
+    exports: z.array(EvidenceExportSchema).default([]),
+    diagnostics: z.array(z.string()).default([]),
+}).superRefine((document, ctx) => {
+    const provided = new Set(document.analyzer.capabilities);
+    for (const [index, reference] of document.references.entries()) {
+        const capability = reference.kind === "import" || reference.kind === "export" || reference.kind === "call" || reference.kind === "contract"
+            ? `${reference.kind}s`
+            : reference.kind;
+        if (!provided.has(capability)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["references", index, "kind"], message: `reference requires analyzer capability ${capability}` });
+        }
+    }
+    if (document.exports.length > 0 && !provided.has("exports")) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["exports"], message: "exports require analyzer capability exports" });
+    }
+});
+export function semanticContentHash(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function evidencePath(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+/, "");
+}
+/** Parse and bind imported evidence to one exact repository-relative file and source revision. */
+export function verifySemanticEvidence(input, expectedFile, content) {
+    const parsed = SemanticEvidenceDocumentSchema.safeParse(input);
+    if (!parsed.success) {
+        return { ok: false, errors: parsed.error.issues.map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`) };
+    }
+    const errors = [];
+    const expected = evidencePath(expectedFile);
+    if (evidencePath(parsed.data.file) !== expected)
+        errors.push(`file mismatch: expected ${expected}, received ${parsed.data.file}`);
+    const actualHash = semanticContentHash(content);
+    if (parsed.data.content_sha256 !== actualHash)
+        errors.push(`content hash mismatch for ${expected}`);
+    return errors.length === 0 ? { ok: true, document: parsed.data, errors: [] } : { ok: false, errors };
+}
+export function assuranceRank(value) {
+    return value === "runtime" ? 3 : value === "ast" ? 2 : 1;
+}

package/dist/semantic-graph-algorithms.js

@@ -0,0 +1,86 @@
+import { relPath } from "./semantic-parsers.js";
+/** Deterministic Tarjan strongly-connected-component detection. */
+export function findModuleCycles(edges) {
+    const adjacency = new Map();
+    for (const edge of edges)
+        adjacency.set(edge.from, [...new Set([...(adjacency.get(edge.from) ?? []), edge.to])].sort());
+    let index = 0;
+    const stack = [];
+    const onStack = new Set();
+    const indices = new Map();
+    const low = new Map();
+    const cycles = [];
+    const visit = (node) => {
+        indices.set(node, index);
+        low.set(node, index);
+        index += 1;
+        stack.push(node);
+        onStack.add(node);
+        for (const next of adjacency.get(node) ?? []) {
+            if (!indices.has(next)) {
+                visit(next);
+                low.set(node, Math.min(low.get(node), low.get(next)));
+            }
+            else if (onStack.has(next))
+                low.set(node, Math.min(low.get(node), indices.get(next)));
+        }
+        if (low.get(node) === indices.get(node)) {
+            const component = [];
+            let popped;
+            do {
+                popped = stack.pop();
+                onStack.delete(popped);
+                component.push(popped);
+            } while (popped !== node);
+            if (component.length > 1)
+                cycles.push(component.sort());
+        }
+    };
+    for (const node of [...new Set(edges.flatMap((edge) => [edge.from, edge.to]))].sort())
+        if (!indices.has(node))
+            visit(node);
+    return cycles.sort((a, b) => a.join("/").localeCompare(b.join("/")));
+}
+/** Reverse closure over file targets and module-only contract/FFI edges. */
+export function computeImpactAnalysis(graph, changedFiles) {
+    const known = new Set(graph.files.map((file) => file.path));
+    const changed = [...new Set(changedFiles.map(relPath))].sort();
+    const affectedFiles = new Set(changed.filter((file) => known.has(file)));
+    const affectedModules = new Set();
+    const moduleOf = new Map(graph.files.map((file) => [file.path, file.module]));
+    for (const file of affectedFiles) {
+        const module = moduleOf.get(file);
+        if (module)
+            affectedModules.add(module);
+    }
+    let progressed = true;
+    while (progressed) {
+        progressed = false;
+        for (const edge of graph.fileEdges) {
+            if ((edge.to && affectedFiles.has(edge.to)) || (edge.toModule && affectedModules.has(edge.toModule))) {
+                if (!affectedFiles.has(edge.from)) {
+                    affectedFiles.add(edge.from);
+                    progressed = true;
+                }
+                if (edge.fromModule && !affectedModules.has(edge.fromModule)) {
+                    affectedModules.add(edge.fromModule);
+                    progressed = true;
+                }
+            }
+        }
+        for (const edge of graph.moduleEdges)
+            if (affectedModules.has(edge.to) && !affectedModules.has(edge.from)) {
+                affectedModules.add(edge.from);
+                progressed = true;
+            }
+    }
+    const impactedFiles = [...affectedFiles].sort();
+    const changedSet = new Set(changed);
+    return {
+        changedFiles: changed,
+        impactedFiles,
+        dependentFiles: impactedFiles.filter((file) => !changedSet.has(file)),
+        impactedModules: [...affectedModules].sort(),
+        unknownChangedFiles: changed.filter((file) => !known.has(file)),
+    };
+}