@zivis/mcp 0.1.8 → 0.1.11

package/dist/matcher/index.js

@@ -0,0 +1,202 @@
+import * as fs from "node:fs/promises";
+import * as fssync from "node:fs";
+import { loadActivePack, findRelevantCapsules, getControl, } from "../pattern-pack/index.js";
+import { walkLanguageFiles } from "./walker.js";
+import { evaluateAstStrategy } from "./ast-eval.js";
+const SUPPORTED_AST_LANGS = new Set([
+    "typescript",
+    "javascript",
+    "python",
+    "go",
+]);
+export async function runMatcher(opts) {
+    const startedAt = Date.now();
+    const handle = await loadActivePack(opts.packId);
+    const artifact = await readArtifact(opts.artifactPath);
+    const relevant = await findRelevantCapsules(handle, artifact);
+    const langsNeeded = collectAstLanguagesNeeded(relevant);
+    const walked = langsNeeded.length > 0
+        ? await walkLanguageFiles(opts.cwd, langsNeeded)
+        : { filesByLanguage: new Map(), filesScanned: 0, filesSkipped: 0 };
+    const controlPresence = await evaluateAllControls(handle, opts.cwd, walked.filesByLanguage);
+    const findings = [];
+    for (const cap of relevant) {
+        const finding = await evaluateCapsule(cap, opts.cwd, walked.filesByLanguage, controlPresence);
+        if (finding)
+            findings.push(finding);
+    }
+    const summary = {
+        trusted_count: findings.filter((f) => f.lane === "trusted").length,
+        inferred_count: findings.filter((f) => f.lane === "inferred").length,
+        total: findings.length,
+    };
+    return {
+        pack: { id: handle.manifest.pack_id, version: handle.manifest.version },
+        artifact_path: opts.artifactPath,
+        cwd: opts.cwd,
+        capsules_relevant: relevant.length,
+        capsules_evaluated: relevant.length,
+        ast_files_scanned: walked.filesScanned,
+        duration_ms: Date.now() - startedAt,
+        summary,
+        findings,
+    };
+}
+async function evaluateCapsule(cap, cwd, filesByLanguage, controlPresence) {
+    const strategies = (cap.strategies ?? []);
+    const fired = [];
+    const evidence = [];
+    let inferenceCandidate;
+    for (const strategy of strategies) {
+        const code = strategy.code;
+        const trusted = strategy.trusted !== false && code !== "INFER" && code !== "SEM" && code !== "REGEX";
+        if (code === "AST") {
+            const lang = (strategy.language ?? "").toLowerCase();
+            if (!SUPPORTED_AST_LANGS.has(lang)) {
+                fired.push({ code, language: lang, trusted, confidence_weight: strategy.confidence_weight, match_count: 0 });
+                continue;
+            }
+            const files = filesByLanguage.get(lang) ?? [];
+            if (files.length === 0) {
+                fired.push({ code, language: lang, trusted, confidence_weight: strategy.confidence_weight, match_count: 0 });
+                continue;
+            }
+            const matches = await evaluateAstStrategy(strategy.expression, lang, files, cwd);
+            fired.push({
+                code,
+                language: lang,
+                trusted,
+                confidence_weight: strategy.confidence_weight,
+                match_count: matches.length,
+            });
+            for (const m of matches) {
+                evidence.push({
+                    file: m.file,
+                    start_line: m.start_line,
+                    end_line: m.end_line,
+                    matched_text: m.matched_text,
+                    strategy_code: code,
+                });
+            }
+        }
+        else if (code === "META") {
+            const result = evaluateMetaStrategy(strategy.expression, controlPresence);
+            fired.push({
+                code,
+                trusted,
+                confidence_weight: strategy.confidence_weight,
+                match_count: result.fired ? 1 : 0,
+            });
+            if (result.fired) {
+                evidence.push({
+                    file: "(synthetic)",
+                    start_line: 0,
+                    matched_text: `META: none_of_controls satisfied; absent: [${result.absent.join(", ")}]`,
+                    strategy_code: code,
+                });
+            }
+        }
+        else if (code === "INFER") {
+            if (cap.model_task_prompt_ref) {
+                inferenceCandidate = {
+                    prompt_ref: cap.model_task_prompt_ref,
+                    expected_output_schema: cap.expected_output_schema,
+                    minimum_context_required: cap.minimum_context_required,
+                    reason: "Capsule has an INFER strategy. Use zivis_threat_get_inference_prompt to retrieve the prompt bundle, gather the indicated code spans, and run the inference in your model.",
+                };
+            }
+            fired.push({ code, trusted: false, confidence_weight: strategy.confidence_weight, match_count: 1 });
+        }
+        else {
+            fired.push({ code, trusted, confidence_weight: strategy.confidence_weight, match_count: 0 });
+        }
+    }
+    const anyFired = fired.some((f) => f.match_count > 0);
+    if (!anyFired)
+        return undefined;
+    const trustedFired = fired.filter((f) => f.trusted && f.match_count > 0).length;
+    const requiredCount = cap.required_evidence_count ?? 1;
+    const lane = trustedFired >= requiredCount ? "trusted" : "inferred";
+    const confidence = Math.min(1, fired.reduce((acc, f) => (f.match_count > 0 ? acc + f.confidence_weight : acc), 0));
+    return {
+        pattern_id: cap.id,
+        pattern_version: cap.version,
+        lane,
+        confidence,
+        fired_strategies: fired,
+        evidence,
+        inference_candidate: inferenceCandidate,
+        safe_summary: cap.safe_summary,
+        threats: cap.threats,
+        repair_contract: cap.repair_contract,
+    };
+}
+async function readArtifact(p) {
+    if (!fssync.existsSync(p)) {
+        throw new Error(`Artifact not found: ${p}`);
+    }
+    const raw = await fs.readFile(p, "utf8");
+    return JSON.parse(raw);
+}
+function collectAstLanguagesNeeded(capsules) {
+    const set = new Set();
+    for (const cap of capsules) {
+        for (const strategy of cap.strategies) {
+            if (strategy.code !== "AST")
+                continue;
+            const lang = (strategy.language ?? "").toLowerCase();
+            if (SUPPORTED_AST_LANGS.has(lang))
+                set.add(lang);
+        }
+    }
+    set.add("typescript");
+    set.add("python");
+    return [...set];
+}
+function evaluateMetaStrategy(expression, presence) {
+    const expr = expression;
+    if (!expr || typeof expr !== "object")
+        return { fired: false, absent: [] };
+    if (expr.none_of_controls && expr.none_of_controls.length > 0) {
+        const checkable = expr.none_of_controls.filter((id) => presence.get(id)?.checkable);
+        if (checkable.length === 0)
+            return { fired: false, absent: [] };
+        const absent = checkable.filter((id) => !presence.get(id).present);
+        if (absent.length === checkable.length) {
+            return { fired: true, absent };
+        }
+        return { fired: false, absent };
+    }
+    return { fired: false, absent: [] };
+}
+async function evaluateAllControls(handle, cwd, filesByLanguage) {
+    const out = new Map();
+    const controlEntries = handle.manifest.controls ?? [];
+    for (const entry of controlEntries) {
+        let control;
+        try {
+            control = await getControl(handle, entry.id);
+        }
+        catch {
+            continue;
+        }
+        let present = false;
+        let checkable = false;
+        for (const det of control.detection ?? []) {
+            const lang = det.language;
+            if (!SUPPORTED_AST_LANGS.has(lang))
+                continue;
+            const files = filesByLanguage.get(lang) ?? [];
+            if (files.length === 0)
+                continue;
+            checkable = true;
+            const matches = await evaluateAstStrategy(det.rule, lang, files, cwd);
+            if (matches.length > 0) {
+                present = true;
+                break;
+            }
+        }
+        out.set(control.id, { present, checkable });
+    }
+    return out;
+}

package/dist/matcher/inference-candidates.d.ts

@@ -0,0 +1,26 @@
+import { type Capsule } from "../pattern-pack/index.js";
+import type { Finding } from "./finding.js";
+export interface BundledInferenceCandidate {
+    candidate_id: string;
+    capsule_id: string;
+    capsule_version: string;
+    pattern_title?: string;
+    prompt: string;
+    expected_output_schema: unknown;
+    evidence_focus: Array<{
+        file: string;
+        start_line: number;
+        end_line?: number;
+        note?: string;
+    }>;
+    minimum_context_required?: {
+        lines?: number;
+        symbols?: string[];
+    };
+    instructions_for_host: string;
+}
+export interface InferenceBundle {
+    inference_candidates: BundledInferenceCandidate[];
+    host_required_action: string;
+}
+export declare function buildInferenceBundle(findings: Finding[], capsuleByPatternId?: Map<string, Capsule>): Promise<InferenceBundle>;

package/dist/matcher/inference-candidates.js

@@ -0,0 +1,81 @@
+import { loadActivePack, getInferencePrompt, } from "../pattern-pack/index.js";
+export async function buildInferenceBundle(findings, capsuleByPatternId) {
+    const candidates = [];
+    let handle;
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        if (!f.inference_candidate)
+            continue;
+        if (!handle) {
+            try {
+                handle = await loadActivePack();
+            }
+            catch {
+                candidates.push(toFallbackCandidate(f, i));
+                continue;
+            }
+        }
+        let promptText;
+        try {
+            promptText = await getInferencePrompt(handle, f.inference_candidate.prompt_ref);
+        }
+        catch {
+            candidates.push(toFallbackCandidate(f, i));
+            continue;
+        }
+        const cap = capsuleByPatternId?.get(f.pattern_id);
+        candidates.push({
+            candidate_id: `ic-${i + 1}`,
+            capsule_id: f.pattern_id,
+            capsule_version: f.pattern_version,
+            pattern_title: cap?.title,
+            prompt: promptText,
+            expected_output_schema: f.inference_candidate.expected_output_schema ?? null,
+            evidence_focus: f.evidence
+                .filter((e) => e.file !== "(synthetic)")
+                .map((e) => ({
+                file: e.file,
+                start_line: e.start_line,
+                end_line: e.end_line,
+                note: e.matched_text ? e.matched_text.slice(0, 200) : undefined,
+            })),
+            minimum_context_required: f.inference_candidate.minimum_context_required,
+            instructions_for_host: "Read the source code at each evidence_focus[*].file:start_line — pull at least minimum_context_required.lines around each span. " +
+                "Attach those snippets to the prompt above. Run the prompt against your model. " +
+                "Return JSON matching expected_output_schema. The output enters the inferred lane.",
+        });
+    }
+    const action = buildHostRequiredAction(candidates);
+    return { inference_candidates: candidates, host_required_action: action };
+}
+function toFallbackCandidate(f, i) {
+    return {
+        candidate_id: `ic-${i + 1}`,
+        capsule_id: f.pattern_id,
+        capsule_version: f.pattern_version,
+        prompt: "",
+        expected_output_schema: f.inference_candidate?.expected_output_schema ?? null,
+        evidence_focus: f.evidence
+            .filter((e) => e.file !== "(synthetic)")
+            .map((e) => ({
+            file: e.file,
+            start_line: e.start_line,
+            end_line: e.end_line,
+        })),
+        minimum_context_required: f.inference_candidate?.minimum_context_required,
+        instructions_for_host: "Inline prompt unavailable. Call zivis_threat_get_inference_prompt with capsule_id=" +
+            f.pattern_id +
+            " to retrieve it.",
+    };
+}
+function buildHostRequiredAction(candidates) {
+    if (candidates.length === 0) {
+        return "No inference candidates emitted by this run. Findings are deterministic-only.";
+    }
+    return (`MANDATORY HOST ACTION: For each of the ${candidates.length} inference_candidate${candidates.length === 1 ? "" : "s"} below, ` +
+        `you MUST: (1) read the source code at evidence_focus[*].file:start_line (open each file, grab at least minimum_context_required.lines of surrounding context), ` +
+        `(2) run the candidate's prompt against your model with that source attached, ` +
+        `(3) produce JSON output matching expected_output_schema. ` +
+        `Do this BEFORE summarizing findings to the user — the inferred-lane verdict from your inference is what the user actually wants. ` +
+        `Each candidate is a self-contained inference task; you do not need to call any other ZIVIS tool to execute it.`);
+}

package/dist/matcher/walker.d.ts

@@ -0,0 +1,7 @@
+export type WalkLanguage = "typescript" | "javascript" | "python" | "go";
+export interface WalkResult {
+    filesByLanguage: Map<WalkLanguage, string[]>;
+    filesScanned: number;
+    filesSkipped: number;
+}
+export declare function walkLanguageFiles(rootDir: string, languages: WalkLanguage[]): Promise<WalkResult>;

package/dist/matcher/walker.js

@@ -0,0 +1,71 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+const HARD_SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    ".yarn",
+    ".pnpm",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".nuxt",
+    ".turbo",
+    ".cache",
+    "coverage",
+    "vendor",
+    "__pycache__",
+    ".venv",
+    "target",
+]);
+const MAX_FILES = 50_000;
+const LANG_EXTENSIONS = {
+    typescript: [".ts", ".tsx"],
+    javascript: [".js", ".jsx", ".mjs", ".cjs"],
+    python: [".py"],
+    go: [".go"],
+};
+export async function walkLanguageFiles(rootDir, languages) {
+    const extToLang = new Map();
+    for (const lang of languages) {
+        for (const ext of LANG_EXTENSIONS[lang])
+            extToLang.set(ext, lang);
+    }
+    const filesByLanguage = new Map();
+    for (const lang of languages)
+        filesByLanguage.set(lang, []);
+    let filesScanned = 0;
+    let filesSkipped = 0;
+    const total = () => Array.from(filesByLanguage.values()).reduce((n, l) => n + l.length, 0);
+    async function visit(dirAbs) {
+        if (total() >= MAX_FILES)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dirAbs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (HARD_SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) {
+                    filesSkipped++;
+                    continue;
+                }
+                await visit(path.join(dirAbs, entry.name));
+                continue;
+            }
+            if (!entry.isFile() && !entry.isSymbolicLink())
+                continue;
+            filesScanned++;
+            const ext = path.extname(entry.name).toLowerCase();
+            const lang = extToLang.get(ext);
+            if (lang) {
+                filesByLanguage.get(lang).push(path.join(dirAbs, entry.name));
+            }
+        }
+    }
+    await visit(rootDir);
+    return { filesByLanguage, filesScanned, filesSkipped };
+}

package/dist/pattern-pack/index.d.ts

@@ -0,0 +1,125 @@
+export interface PackManifest {
+    schema_version: "1.0.0";
+    pack_id: string;
+    pack_name: string;
+    version: string;
+    built_at: string;
+    tier: "public_teaser" | "public" | "customer_safe";
+    description?: string;
+    capsules: ManifestCapsuleEntry[];
+    prompts: ManifestPromptEntry[];
+    controls?: ManifestControlEntry[];
+}
+export interface ManifestCapsuleEntry {
+    id: string;
+    version: string;
+    path: string;
+    sha256: string;
+    category?: string;
+    lifecycle?: string;
+    applicable_languages?: string[];
+}
+export interface ManifestPromptEntry {
+    path: string;
+    sha256: string;
+    capsule_id?: string;
+}
+export interface ManifestControlEntry {
+    id: string;
+    path: string;
+    sha256: string;
+    applicable_languages?: string[];
+}
+export interface ControlDetectionRule {
+    language: "typescript" | "javascript" | "python" | "go";
+    rule: unknown;
+}
+export interface Control {
+    id: string;
+    description?: string;
+    applicable_languages: string[];
+    detection: ControlDetectionRule[];
+    lifecycle?: string;
+    owner?: string;
+}
+export interface RelevanceTerm {
+    dependency?: string;
+    direct_only?: boolean;
+    language?: string;
+    framework?: string;
+    evidence?: string;
+}
+export interface RelevanceFilter {
+    any_of?: RelevanceTerm[];
+    all_of?: RelevanceTerm[];
+    none_of?: RelevanceTerm[];
+}
+export interface Capsule {
+    id: string;
+    slug: string;
+    version: string;
+    category: string;
+    title?: string;
+    headline?: string;
+    description?: string;
+    detection_tier: "public" | "proprietary";
+    scoring_tier: "public" | "proprietary";
+    applicable_languages: string[];
+    relevance_filter?: RelevanceFilter;
+    strategies: unknown[];
+    required_evidence_count: number;
+    threats?: unknown[];
+    lifecycle: "draft" | "active" | "deprecated";
+    sensitivity_level?: "public_teaser" | "customer_safe" | "zivis_confidential";
+    safe_summary?: string;
+    detect_when?: string;
+    risk_hints?: string[];
+    architectural_signals?: string[];
+    model_task_prompt_ref?: string;
+    expected_output_schema?: unknown;
+    minimum_context_required?: {
+        lines?: number;
+        symbols?: string[];
+    };
+    related_patterns?: string[];
+    repair_contract?: {
+        allowed?: string[];
+        forbidden?: string[];
+    };
+    validation_contract?: {
+        requires_tests_pass?: boolean;
+        requires_static_rules?: string[];
+    };
+}
+export interface PackHandle {
+    manifest: PackManifest;
+    rootDir: string;
+}
+export interface GraphArtifactView {
+    scope: {
+        languages?: string[];
+    };
+    nodes: Array<{
+        type: string;
+        evidence: Array<{
+            kind: string;
+        }>;
+        attributes?: {
+            package?: string;
+        };
+    }>;
+}
+export declare function loadActivePack(packId?: string): Promise<PackHandle>;
+export declare function getCapsule(handle: PackHandle, capsuleId: string): Promise<Capsule>;
+export declare function getInferencePrompt(handle: PackHandle, ref: string): Promise<string>;
+export declare function listCapsuleIds(handle: PackHandle): Promise<string[]>;
+export declare function listControlIds(handle: PackHandle): Promise<string[]>;
+export declare function getControl(handle: PackHandle, controlId: string): Promise<Control>;
+export declare function findRelevantCapsules(handle: PackHandle, artifact: GraphArtifactView): Promise<Capsule[]>;
+interface EvalContext {
+    packageNames: Set<string>;
+    languages: Set<string>;
+    evidenceKinds: Set<string>;
+}
+export declare function matchesRelevance(cap: Capsule, ctx: EvalContext): boolean;
+export {};