@zivis/mcp 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/lib/inspect-cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * inspect-cache — shared helpers for locating local `zivis inspect` artifacts.
+ *
+ * The repo-id derivation must match the algorithm `zivis inspect` uses when it
+ * writes runs (git remote URL hash, falling back to root-path hash). Both
+ * `zivis_get_started` and `zivis_threat_guide` read this cache to avoid
+ * nagging the user to re-inspect when a fresh run already exists on disk.
+ */
+export interface LocatedArtifact {
+    path: string;
+    mtimeMs: number;
+}
+export declare function userCacheRoot(): string;
+export declare function deriveRepoId(cwd: string): Promise<string>;
+/**
+ * Locate the most recent inspect artifact for THIS repo.
+ *
+ * Returns undefined if no runs exist for this repo, even when other repos
+ * have artifacts. Returns both the path and mtime so callers can apply
+ * freshness logic without re-stat'ing.
+ */
+export declare function locateLatestArtifact(cwd: string): Promise<LocatedArtifact | undefined>;
+/**
+ * Default freshness TTL for the inspect cache. After this, callers should
+ * treat the artifact as stale and recommend re-running inspect.
+ *
+ * 15 min matches the typical IDE-session length for "I just inspected; don't
+ * make me do it again." Override via ZIVIS_INSPECT_CACHE_TTL_MS.
+ */
+export declare const DEFAULT_INSPECT_CACHE_TTL_MS: number;
+export declare function inspectCacheTtlMs(): number;
+export declare function isFresh(mtimeMs: number, now?: number): boolean;

package/dist/lib/inspect-cache.js

@@ -0,0 +1,99 @@
+/**
+ * inspect-cache — shared helpers for locating local `zivis inspect` artifacts.
+ *
+ * The repo-id derivation must match the algorithm `zivis inspect` uses when it
+ * writes runs (git remote URL hash, falling back to root-path hash). Both
+ * `zivis_get_started` and `zivis_threat_guide` read this cache to avoid
+ * nagging the user to re-inspect when a fresh run already exists on disk.
+ */
+import * as fs from "node:fs/promises";
+import * as fssync from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+export function userCacheRoot() {
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Caches", "zivis");
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local");
+        return path.join(localAppData, "zivis", "Cache");
+    }
+    const xdg = process.env.XDG_CACHE_HOME;
+    return path.join(xdg ?? path.join(home, ".cache"), "zivis");
+}
+export async function deriveRepoId(cwd) {
+    const remote = await tryGit(cwd, "remote get-url origin");
+    if (remote) {
+        return "remote-" + sha256Short(remote);
+    }
+    return "path-" + sha256Short(cwd);
+}
+async function tryGit(cwd, args) {
+    try {
+        const { stdout } = await execAsync(`git ${args}`, { cwd });
+        const value = stdout.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sha256Short(value) {
+    return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+/**
+ * Locate the most recent inspect artifact for THIS repo.
+ *
+ * Returns undefined if no runs exist for this repo, even when other repos
+ * have artifacts. Returns both the path and mtime so callers can apply
+ * freshness logic without re-stat'ing.
+ */
+export async function locateLatestArtifact(cwd) {
+    const repoId = await deriveRepoId(cwd);
+    const runsDir = path.join(userCacheRoot(), "repos", repoId, "inspect", "runs");
+    if (!fssync.existsSync(runsDir))
+        return undefined;
+    const candidates = [];
+    for (const entry of await fs.readdir(runsDir)) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const full = path.join(runsDir, entry);
+        try {
+            const stat = await fs.stat(full);
+            candidates.push({ path: full, mtimeMs: stat.mtimeMs });
+        }
+        catch {
+            // skip
+        }
+    }
+    if (candidates.length === 0)
+        return undefined;
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return candidates[0];
+}
+/**
+ * Default freshness TTL for the inspect cache. After this, callers should
+ * treat the artifact as stale and recommend re-running inspect.
+ *
+ * 15 min matches the typical IDE-session length for "I just inspected; don't
+ * make me do it again." Override via ZIVIS_INSPECT_CACHE_TTL_MS.
+ */
+export const DEFAULT_INSPECT_CACHE_TTL_MS = 15 * 60 * 1000;
+export function inspectCacheTtlMs() {
+    const raw = process.env.ZIVIS_INSPECT_CACHE_TTL_MS;
+    if (!raw)
+        return DEFAULT_INSPECT_CACHE_TTL_MS;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_INSPECT_CACHE_TTL_MS;
+    return parsed;
+}
+export function isFresh(mtimeMs, now = Date.now()) {
+    return now - mtimeMs <= inspectCacheTtlMs();
+}
+//# sourceMappingURL=inspect-cache.js.map

package/dist/lib/inspect-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-cache.js","sourceRoot":"","sources":["../../src/lib/inspect-cache.ts"],"names":[],"mappings":"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"}

package/dist/matcher/ast-eval.d.ts

@@ -0,0 +1,27 @@
+/**
+ * AST strategy evaluator.
+ *
+ * Wraps @ast-grep/napi. Capsule strategies of code:AST carry a YAML rule
+ * body in `expression` (already parsed by js-yaml when the capsule was
+ * loaded). We run that rule against source files of the strategy's
+ * language and collect line spans as evidence.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 3 — Matching engine)
+ */
+export type AstLanguage = "typescript" | "javascript" | "python" | "go";
+export interface AstMatch {
+    file: string;
+    start_line: number;
+    end_line: number;
+    matched_text: string;
+}
+/**
+ * Run an ast-grep rule (already parsed from the capsule YAML) against the
+ * given source files and return all matches.
+ *
+ * The expression is the capsule's `strategy.expression` field. Capsules
+ * may write the rule as either:
+ *   - a raw string (parsed as YAML) containing a top-level `rule:` block, or
+ *   - a structured object (already an `{ rule: { ... } }` shape)
+ */
+export declare function evaluateAstStrategy(expression: unknown, language: AstLanguage, files: string[], rootDir: string): Promise<AstMatch[]>;

package/dist/matcher/ast-eval.js

@@ -0,0 +1,132 @@
+/**
+ * AST strategy evaluator.
+ *
+ * Wraps @ast-grep/napi. Capsule strategies of code:AST carry a YAML rule
+ * body in `expression` (already parsed by js-yaml when the capsule was
+ * loaded). We run that rule against source files of the strategy's
+ * language and collect line spans as evidence.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 3 — Matching engine)
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import * as napi from "@ast-grep/napi";
+let registered = false;
+async function ensureLanguagesRegistered() {
+    if (registered)
+        return;
+    // ts/js are built into napi; python and go come from dynamic language packs.
+    const py = (await import("@ast-grep/lang-python")).default;
+    const go = (await import("@ast-grep/lang-go")).default;
+    napi.registerDynamicLanguage({ python: py, go: go });
+    registered = true;
+}
+/**
+ * Run an ast-grep rule (already parsed from the capsule YAML) against the
+ * given source files and return all matches.
+ *
+ * The expression is the capsule's `strategy.expression` field. Capsules
+ * may write the rule as either:
+ *   - a raw string (parsed as YAML) containing a top-level `rule:` block, or
+ *   - a structured object (already an `{ rule: { ... } }` shape)
+ */
+export async function evaluateAstStrategy(expression, language, files, rootDir) {
+    await ensureLanguagesRegistered();
+    const rule = normalizeExpressionToRule(expression);
+    if (!rule)
+        return [];
+    const matches = [];
+    const langKey = languageKey(language);
+    for (const file of files) {
+        let raw;
+        try {
+            raw = await fs.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!raw)
+            continue;
+        let root;
+        try {
+            root = napi.parse(langKey, raw);
+        }
+        catch {
+            continue;
+        }
+        let foundNodes;
+        try {
+            // Cast: napi types restrict findAll to string|number, but at runtime it
+            // accepts a NapiConfig object (which is what capsule rules deserialize to).
+            foundNodes = root.root().findAll(rule);
+        }
+        catch {
+            // ast-grep throws on malformed rules; skip this strategy on this file.
+            continue;
+        }
+        for (const node of foundNodes) {
+            const range = node.range();
+            matches.push({
+                file: relPosix(rootDir, file),
+                start_line: (range.start.line ?? 0) + 1,
+                end_line: (range.end.line ?? 0) + 1,
+                matched_text: truncate(node.text(), 240),
+            });
+        }
+    }
+    return matches;
+}
+// ── Helpers ──
+function normalizeExpressionToRule(expression) {
+    if (typeof expression === "string") {
+        try {
+            return ensureRuleWrapper(yaml.load(expression));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (expression && typeof expression === "object") {
+        return ensureRuleWrapper(expression);
+    }
+    return undefined;
+}
+/**
+ * ast-grep's findAll requires a top-level `rule:` wrapper. Capsule AST
+ * strategies have it explicit in YAML; control detection rules carry just
+ * the bare rule body. Wrap consistently here so both shapes evaluate.
+ *
+ * NapiConfig keys recognized as outer-level: rule, constraints, utils,
+ * filters, language, transform, fix. Any of those at the top means we're
+ * already wrapped.
+ */
+function ensureRuleWrapper(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return parsed;
+    const obj = parsed;
+    if ("rule" in obj)
+        return obj;
+    return { rule: obj };
+}
+function languageKey(lang) {
+    // ts and tsx are separate engines in napi; we use ts for .ts/.tsx and
+    // js for .js/.jsx/.mjs/.cjs. The matcher passes the file's language tag,
+    // not the file extension — so .tsx files routed as 'typescript' work.
+    switch (lang) {
+        case "typescript": return "ts";
+        case "javascript": return "js";
+        case "python": return "python";
+        case "go": return "go";
+    }
+}
+function relPosix(rootDir, abs) {
+    const rel = path.relative(rootDir, abs);
+    return rel.split(path.sep).join("/");
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + "…";
+}
+//# sourceMappingURL=ast-eval.js.map

package/dist/matcher/ast-eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-eval.js","sourceRoot":"","sources":["../../src/matcher/ast-eval.ts"],"names":[],"mappings":"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"}

package/dist/matcher/finding.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Normalized Finding type emitted by the matcher.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md
+ *   "Normalize outputs to a single finding schema (patternId/version,
+ *    matched graph evidence, confidence, lane, explanation, remediation)."
+ *
+ * Lane determination:
+ *   - trusted: count(fired deterministic strategies) >= required_evidence_count
+ *   - inferred: any strategy fired but bar not met (host LLM should confirm)
+ *   - (no finding emitted otherwise)
+ */
+export type Lane = "trusted" | "inferred";
+export interface MatchedEvidence {
+    /** Where the strategy fired. */
+    file: string;
+    start_line: number;
+    end_line?: number;
+    /** Truncated source snippet for human review (NOT for re-execution). */
+    matched_text?: string;
+    /** Which strategy code emitted this evidence (AST, GRAPH, META, INFER, ...). */
+    strategy_code: string;
+}
+export interface FiredStrategy {
+    code: string;
+    language?: string;
+    trusted: boolean;
+    confidence_weight: number;
+    match_count: number;
+}
+export interface InferenceCandidate {
+    prompt_ref: string;
+    expected_output_schema?: unknown;
+    minimum_context_required?: {
+        lines?: number;
+        symbols?: string[];
+    };
+    /** Why the host LLM should run inference on this finding. */
+    reason: string;
+}
+export interface Finding {
+    pattern_id: string;
+    pattern_version: string;
+    lane: Lane;
+    /** 0..1 — sum of fired-strategy weights, capped at 1. */
+    confidence: number;
+    /** Strategies that contributed (AST matches, INFER candidate, etc.). */
+    fired_strategies: FiredStrategy[];
+    /** Evidence spans from deterministic strategies that fired. */
+    evidence: MatchedEvidence[];
+    /** Present iff the capsule has an INFER strategy — host LLM should pick this up. */
+    inference_candidate?: InferenceCandidate;
+    /** Surfaced from the capsule for the host's framing. */
+    safe_summary?: string;
+    threats?: unknown[];
+    repair_contract?: unknown;
+}
+export interface MatcherSummary {
+    trusted_count: number;
+    inferred_count: number;
+    total: number;
+}
+export interface MatcherResult {
+    pack: {
+        id: string;
+        version: string;
+    };
+    artifact_path: string;
+    cwd: string;
+    capsules_relevant: number;
+    capsules_evaluated: number;
+    ast_files_scanned: number;
+    duration_ms: number;
+    summary: MatcherSummary;
+    findings: Finding[];
+}

package/dist/matcher/finding.js

@@ -0,0 +1,14 @@
+/**
+ * Normalized Finding type emitted by the matcher.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md
+ *   "Normalize outputs to a single finding schema (patternId/version,
+ *    matched graph evidence, confidence, lane, explanation, remediation)."
+ *
+ * Lane determination:
+ *   - trusted: count(fired deterministic strategies) >= required_evidence_count
+ *   - inferred: any strategy fired but bar not met (host LLM should confirm)
+ *   - (no finding emitted otherwise)
+ */
+export {};
+//# sourceMappingURL=finding.js.map

package/dist/matcher/finding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finding.js","sourceRoot":"","sources":["../../src/matcher/finding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/matcher/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Phase 3 matcher — runs the local public pack against a repo graph
+ * artifact + the source files in cwd.
+ *
+ * v1 scope (locked):
+ *   - AST strategies are evaluated for real (via @ast-grep/napi)
+ *   - INFER strategies emit inference candidates; host LLM runs them
+ *   - GRAPH / META / DEP / CONFIG / STRUCT / REGEX / SEM / RECON: not
+ *     evaluated yet, but visible in `fired_strategies` as `match_count: 0`
+ *     so we don't lose the contract.
+ *
+ * Lane assignment per finding:
+ *   - trusted: count of fired deterministic (trusted: true) strategies
+ *     reaches `required_evidence_count`
+ *   - inferred: any strategy fired but bar not met
+ *   - (no finding) if nothing fired
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 3)
+ */
+import type { MatcherResult } from "./finding.js";
+export type { Finding, FiredStrategy, MatchedEvidence, MatcherResult, Lane } from "./finding.js";
+export interface RunMatcherOpts {
+    /** Path to the RepoGraphArtifactV1 JSON produced by `zivis inspect`. */
+    artifactPath: string;
+    /** Repo root for source-file walking (capsule AST strategies match against this). */
+    cwd: string;
+    /** Override default pack id. */
+    packId?: string;
+}
+export declare function runMatcher(opts: RunMatcherOpts): Promise<MatcherResult>;