@zivis/cli 0.1.0-alpha.32 → 0.1.0-alpha.33

package/dist/internal/extractor/graph-builder.js

@@ -0,0 +1,283 @@
+/**
+ * Build a RepoGraphArtifactV1 from an ExtractionResult.
+ *
+ * The existing extractor emits an entity-list shape (components,
+ * externalServices, dataStores, manifests). This builder is the canonical
+ * translator from that internal intermediate into the graph artifact that
+ * downstream pattern matching, threat modeling, and evidence storage all
+ * consume.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 1)
+ * Schema: schemas/repo-graph-artifact.schema.json
+ *
+ * v1 scope (locked): three node types (service, endpoint, external_dependency)
+ * and two edge types (exposes, depends_on). Datastores and the corresponding
+ * reads/writes edges are deferred to Phase 1.5.
+ *
+ * Lane assignment for v1: every node and edge produced by deterministic
+ * adapter output is `trusted`. Inferred-lane nodes are introduced later by
+ * the matching engine (Phase 3), not by extraction.
+ */
+const TRUSTED_LANE = "trusted";
+const TRUSTED_SOURCE = "inspect.trusted";
+export function buildRepoGraphArtifact(result, opts = {}) {
+    const nodes = [];
+    const edges = [];
+    // Service nodes — every component that isn't an external service or pure datastore.
+    // The existing extractor models datastores via `dataStores` and external SDKs via
+    // `externalServices`; `components` covers code-defined services and frontends.
+    // Skip components that arrive with empty evidence — schema requires minItems: 1.
+    const serviceById = new Map();
+    for (const component of result.components) {
+        if (component.kind === "external_service" || component.kind === "data_store") {
+            continue;
+        }
+        if (component.evidence.length === 0)
+            continue;
+        const node = buildServiceNode(component);
+        serviceById.set(node.id, node);
+        nodes.push(node);
+    }
+    // Endpoint nodes + exposes edges — derived from each service's http_route evidence.
+    // Non-canonical methods (e.g. Express `app.use()` mounts emitted by the TS adapter)
+    // are dropped here — they're middleware mounts, not endpoints. Fixing them belongs
+    // upstream in the adapter; the graph-builder enforces the contract.
+    for (const component of result.components) {
+        const owningServiceId = serviceIdFor(component);
+        if (!serviceById.has(owningServiceId))
+            continue;
+        const seenEndpoints = new Set();
+        for (const ev of component.evidence) {
+            if (ev.kind !== "http_route")
+                continue;
+            const method = canonicalMethod(ev.method);
+            if (!method)
+                continue;
+            const endpointNode = buildEndpointNode(owningServiceId, component.language, ev, method);
+            if (seenEndpoints.has(endpointNode.id))
+                continue;
+            seenEndpoints.add(endpointNode.id);
+            nodes.push(endpointNode);
+            edges.push(buildExposesEdge(owningServiceId, endpointNode.id, ev));
+        }
+    }
+    // External dependency nodes — one per (registry, package) tuple.
+    // Manifest-only deps (no callSites) fall back to manifest evidence so they still
+    // satisfy the schema's evidence: minItems: 1 invariant.
+    const manifestEvidenceByPackage = indexManifestsByPackage(result);
+    const depById = new Map();
+    for (const ext of result.externalServices) {
+        const node = buildExternalDependencyNode(ext, manifestEvidenceByPackage.get(ext.package) ?? []);
+        if (depById.has(node.id))
+            continue;
+        if (node.evidence.length === 0)
+            continue; // truly orphaned — skip
+        depById.set(node.id, node);
+        nodes.push(node);
+    }
+    // File-to-service index for resolving callSites into depends_on edges.
+    const fileToServiceId = buildFileToServiceIndex(result.components, serviceById);
+    for (const ext of result.externalServices) {
+        const depId = externalDepId(ext);
+        const seenServiceIds = new Set();
+        const evidenceByService = new Map();
+        for (const callSite of ext.callSites) {
+            const serviceId = fileToServiceId.get(callSite.file);
+            if (!serviceId)
+                continue;
+            seenServiceIds.add(serviceId);
+            const list = evidenceByService.get(serviceId) ?? [];
+            list.push(toImportEvidence(callSite, ext.package));
+            evidenceByService.set(serviceId, list);
+        }
+        for (const serviceId of seenServiceIds) {
+            edges.push(buildDependsOnEdge(serviceId, depId, evidenceByService.get(serviceId) ?? []));
+        }
+    }
+    const provenance = {
+        root_dir: result.scope.rootDir,
+        analysis_mode: opts.analysisMode ?? "local",
+        ...(opts.repoId ? { repo_id: opts.repoId } : {}),
+        ...(opts.commitSha ? { commit_sha: opts.commitSha } : {}),
+        ...(opts.branch ? { branch: opts.branch } : {}),
+        ...(opts.applicationId ? { application_id: opts.applicationId } : {}),
+    };
+    const languagesFromManifests = new Set(result.manifests.map((m) => normalizeLanguage(m.language)).filter(Boolean));
+    return {
+        version: "1.0.0",
+        kind: "repo_graph_artifact",
+        extracted_at: result.extractedAt,
+        extractor: result.extractor,
+        provenance,
+        scope: {
+            files_scanned: result.scope.filesScanned,
+            files_skipped: result.scope.filesSkipped,
+            duration_ms: result.scope.durationMs,
+            languages: [...languagesFromManifests],
+        },
+        nodes,
+        edges,
+    };
+}
+// ── Node builders ──
+function buildServiceNode(component) {
+    const id = serviceIdFor(component);
+    return {
+        id,
+        type: "service",
+        name: component.name,
+        lane: TRUSTED_LANE,
+        source: TRUSTED_SOURCE,
+        confidence: 1,
+        language: normalizeLanguage(component.language),
+        evidence: component.evidence.map(toEvidenceSpan),
+        attributes: {
+            ...(component.framework ? { framework: component.framework } : {}),
+            source_files: component.sourceFiles,
+        },
+    };
+}
+function buildEndpointNode(serviceId, language, ev, method) {
+    const id = `endpoint::${stripPrefix(serviceId, "service::")}::${method}::${ev.path}`;
+    return {
+        id,
+        type: "endpoint",
+        name: `${method} ${ev.path}`,
+        lane: TRUSTED_LANE,
+        source: TRUSTED_SOURCE,
+        confidence: 1,
+        language: normalizeLanguage(language),
+        evidence: [toEvidenceSpan(ev)],
+        attributes: { method, path: ev.path },
+    };
+}
+function buildExternalDependencyNode(ext, manifestFallback) {
+    const registry = registryFor(ext);
+    const evidence = ext.callSites.length > 0
+        ? ext.callSites.map((cs) => toImportEvidence(cs, ext.package))
+        : manifestFallback;
+    return {
+        id: externalDepId(ext),
+        type: "external_dependency",
+        name: ext.name,
+        lane: TRUSTED_LANE,
+        source: TRUSTED_SOURCE,
+        confidence: 1,
+        evidence,
+        attributes: {
+            package: ext.package,
+            registry,
+            ...(ext.version ? { version: ext.version } : {}),
+            ...(ext.kind ? { kind: ext.kind } : {}),
+        },
+    };
+}
+function indexManifestsByPackage(result) {
+    const idx = new Map();
+    for (const m of result.manifests) {
+        for (const pkg of Object.keys(m.dependencies)) {
+            const span = { file: m.file, kind: "manifest", detail: { package: pkg } };
+            const list = idx.get(pkg) ?? [];
+            list.push(span);
+            idx.set(pkg, list);
+        }
+    }
+    return idx;
+}
+function buildExposesEdge(serviceId, endpointId, ev) {
+    return {
+        id: `exposes::${serviceId}::${endpointId}`,
+        type: "exposes",
+        source_id: serviceId,
+        target_id: endpointId,
+        lane: TRUSTED_LANE,
+        source: TRUSTED_SOURCE,
+        confidence: 1,
+        evidence: [toEvidenceSpan(ev)],
+    };
+}
+function buildDependsOnEdge(serviceId, depId, evidence) {
+    return {
+        id: `depends_on::${serviceId}::${depId}`,
+        type: "depends_on",
+        source_id: serviceId,
+        target_id: depId,
+        lane: TRUSTED_LANE,
+        source: TRUSTED_SOURCE,
+        confidence: 1,
+        evidence,
+    };
+}
+// ── Helpers ──
+function serviceIdFor(component) {
+    return `service::${component.language}::${component.name}`;
+}
+function externalDepId(ext) {
+    const registry = registryFor(ext);
+    return `external_dependency::${registry}::${ext.package}`;
+}
+function registryFor(ext) {
+    // Heuristic — the existing extractor doesn't tag registry, so derive from package shape.
+    if (ext.package.startsWith("github.com/"))
+        return "go";
+    if (ext.package.startsWith("@") || /^[a-z0-9-]+$/.test(ext.package)) {
+        // npm + pypi share many shapes; lean npm by default since most ai_sdks live there.
+        // PyPI-only packages can be retagged once adapters expose registry directly.
+        return "npm";
+    }
+    return "npm";
+}
+const CANONICAL_METHODS = new Set([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+    "WS",
+    "SSE",
+    "RPC",
+]);
+function canonicalMethod(method) {
+    const upper = method.toUpperCase();
+    return CANONICAL_METHODS.has(upper) ? upper : undefined;
+}
+function normalizeLanguage(lang) {
+    return lang;
+}
+function buildFileToServiceIndex(components, servicesById) {
+    const idx = new Map();
+    for (const component of components) {
+        const id = serviceIdFor(component);
+        if (!servicesById.has(id))
+            continue;
+        for (const file of component.sourceFiles) {
+            if (!idx.has(file))
+                idx.set(file, id);
+        }
+    }
+    return idx;
+}
+function toEvidenceSpan(ev) {
+    const base = { file: ev.file, start_line: ev.line, kind: ev.kind };
+    if (ev.kind === "http_route") {
+        return { ...base, detail: { method: ev.method, path: ev.path } };
+    }
+    if (ev.kind === "import") {
+        return { ...base, detail: { package: ev.package } };
+    }
+    return base;
+}
+function toImportEvidence(loc, pkg) {
+    return {
+        file: loc.file,
+        start_line: loc.line,
+        kind: "import",
+        detail: { package: pkg },
+    };
+}
+function stripPrefix(value, prefix) {
+    return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+//# sourceMappingURL=graph-builder.js.map

package/dist/internal/extractor/graph-builder.js.map

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

package/dist/internal/extractor/graph-types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * TypeScript interfaces for RepoGraphArtifactV1.
+ *
+ * Canonical source: schemas/repo-graph-artifact.schema.json
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 1)
+ *
+ * The JSON schema is authoritative — these types must stay in sync. A
+ * repo-level test (planned) validates extractor output against the schema
+ * to catch drift.
+ */
+export type Lane = "trusted" | "inferred";
+export type Source = "inspect.trusted" | "inspect.inferred";
+export type GraphLanguage = "typescript" | "javascript" | "python" | "go";
+export type AnalysisMode = "local" | "cloud";
+export type EvidenceKind = "import" | "http_route" | "config" | "manifest" | "decorator" | "annotation";
+export type NodeType = "service" | "endpoint" | "external_dependency";
+export type EdgeType = "exposes" | "depends_on";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "WS" | "SSE" | "RPC";
+export type DependencyRegistry = "npm" | "pypi" | "go";
+export interface EvidenceSpan {
+    file: string;
+    start_line?: number;
+    end_line?: number;
+    kind: EvidenceKind;
+    detail?: Record<string, unknown>;
+}
+export interface ServiceAttributes {
+    framework?: string;
+    source_files?: string[];
+}
+export interface EndpointAttributes {
+    method: HttpMethod;
+    path: string;
+}
+export interface ExternalDependencyAttributes {
+    package: string;
+    version?: string;
+    registry: DependencyRegistry;
+    kind?: string;
+}
+export type NodeAttributes = ServiceAttributes | EndpointAttributes | ExternalDependencyAttributes;
+interface BaseNode {
+    id: string;
+    name: string;
+    lane: Lane;
+    source: Source;
+    confidence?: number;
+    language?: GraphLanguage;
+    evidence: EvidenceSpan[];
+}
+export interface ServiceNode extends BaseNode {
+    type: "service";
+    attributes?: ServiceAttributes;
+}
+export interface EndpointNode extends BaseNode {
+    type: "endpoint";
+    attributes: EndpointAttributes;
+}
+export interface ExternalDependencyNode extends BaseNode {
+    type: "external_dependency";
+    attributes: ExternalDependencyAttributes;
+}
+export type GraphNode = ServiceNode | EndpointNode | ExternalDependencyNode;
+export interface GraphEdge {
+    id: string;
+    type: EdgeType;
+    source_id: string;
+    target_id: string;
+    lane: Lane;
+    source: Source;
+    confidence?: number;
+    evidence?: EvidenceSpan[];
+    attributes?: Record<string, unknown>;
+}
+export interface GraphProvenance {
+    root_dir: string;
+    repo_id?: string;
+    commit_sha?: string;
+    branch?: string;
+    application_id?: string;
+    analysis_mode: AnalysisMode;
+}
+export interface GraphScope {
+    files_scanned: number;
+    files_skipped: number;
+    duration_ms: number;
+    languages?: GraphLanguage[];
+}
+export interface RepoGraphArtifactV1 {
+    version: "1.0.0";
+    kind: "repo_graph_artifact";
+    extracted_at: string;
+    extractor: string;
+    provenance: GraphProvenance;
+    scope: GraphScope;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+export {};

package/dist/internal/extractor/graph-types.js

@@ -0,0 +1,12 @@
+/**
+ * TypeScript interfaces for RepoGraphArtifactV1.
+ *
+ * Canonical source: schemas/repo-graph-artifact.schema.json
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 1)
+ *
+ * The JSON schema is authoritative — these types must stay in sync. A
+ * repo-level test (planned) validates extractor output against the schema
+ * to catch drift.
+ */
+export {};
+//# sourceMappingURL=graph-types.js.map

package/dist/internal/extractor/graph-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-types.js","sourceRoot":"","sources":["../../../src/internal/extractor/graph-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

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

@@ -0,0 +1,123 @@
+/**
+ * Local pattern pack reader.
+ *
+ * The pack ships bundled inside the @zivis/cli npm package at
+ * `dist/pattern-packs/<pack-id>-<version>/`. On first use we copy it to
+ * `~/Library/Caches/zivis/pattern-packs/<pack-id>-<version>/` so future
+ * runs read from the user cache directly.
+ *
+ * The reader serves both:
+ *  - `zivis inspect` matcher (Phase 3) — deterministic + inference
+ *    candidates evaluated against the local repo graph artifact.
+ *  - MCP tools that surface relevant capsules mid-IDE-conversation.
+ *
+ * Plan: docs/plans/LOCAL-REPO-GRAPH-IMPLEMENTATION.md (Phase 2A)
+ * Schemas:
+ *   - schemas/pattern-pack-manifest.schema.json (manifest.json)
+ *   - schemas/pattern-detection-card.schema.json (capsule yaml)
+ */
+import type { RepoGraphArtifactV1, GraphLanguage } from "../extractor/graph-types.js";
+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[];
+}
+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 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;
+}
+/**
+ * Locate the active pack and ensure it's available in the user cache.
+ *
+ * Resolution order:
+ *  1. ZIVIS_PACK_DIR env var (override for tests / enterprise air-gap imports)
+ *  2. User cache, if present
+ *  3. Bundled pack inside @zivis/cli (copied to user cache on first use)
+ */
+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[]>;
+/**
+ * Evaluate each capsule's relevance_filter against the repo graph artifact
+ * and return the subset whose filter passes. Used by:
+ *   - chat-session surface: "what patterns might apply to this codebase?"
+ *   - matcher pre-filter: skip capsules that can't fire on this graph
+ */
+export declare function findRelevantCapsules(handle: PackHandle, artifact: RepoGraphArtifactV1): Promise<Capsule[]>;
+interface EvalContext {
+    packageNames: Set<string>;
+    languages: Set<GraphLanguage>;
+    evidenceKinds: Set<string>;
+}
+export declare function matchesRelevance(cap: Capsule, ctx: EvalContext): boolean;
+export {};