vaspera 2.7.0 → 2.9.0

package/dist/telemetry/registry.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Scan Registry Module
+ *
+ * Maintains a persistent registry of all scans for analytics,
+ * case study identification, and compliance auditing.
+ *
+ * @module telemetry/registry
+ */
+import type { Severity, CertificationLevel } from "../certification/types.js";
+/**
+ * A record of a completed scan
+ */
+export interface ScanRecord {
+    /** Unique scan ID */
+    id: string;
+    /** Certification ID if certified */
+    certificationId?: string;
+    /** Project path (can be redacted) */
+    projectPath: string;
+    /** SHA256 hash of project path for matching */
+    projectHash: string;
+    /** Repository URL (if opted in) */
+    repoUrl?: string;
+    /** Organization name (if opted in) */
+    orgName?: string;
+    /** User email (if opted in) */
+    userEmail?: string;
+    /** When the scan was performed */
+    scanDate: string;
+    /** Certification level achieved */
+    level?: CertificationLevel;
+    /** Overall score (0-100) */
+    score?: number;
+    /** Scan duration in milliseconds */
+    duration: number;
+    /** Findings by severity */
+    findingsSummary: Record<Severity, number>;
+    /** Total findings */
+    totalFindings: number;
+    /** Scanners that were run */
+    scannersRun: string[];
+    /** Frameworks assessed */
+    frameworksAssessed: string[];
+    /** Whether the scan succeeded */
+    success: boolean;
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Whether user consented to case study */
+    caseStudyConsent?: boolean;
+    /** Tags for categorization */
+    tags?: string[];
+}
+/**
+ * Summary of findings for analytics
+ */
+export interface FindingSummary {
+    /** Rule/check ID */
+    ruleId: string;
+    /** Scanner that found it */
+    scanner: string;
+    /** Category */
+    category: string;
+    /** Severity */
+    severity: Severity;
+    /** Number of occurrences across all scans */
+    occurrences: number;
+    /** Number of unique projects affected */
+    projectsAffected: number;
+}
+/**
+ * Analytics summary
+ */
+export interface RegistryAnalytics {
+    /** Total scans recorded */
+    totalScans: number;
+    /** Successful scans */
+    successfulScans: number;
+    /** Failed scans */
+    failedScans: number;
+    /** Scans by certification level */
+    byLevel: Record<CertificationLevel, number>;
+    /** Scans by framework */
+    byFramework: Record<string, number>;
+    /** Scans by scanner */
+    byScanner: Record<string, number>;
+    /** Scans by month (YYYY-MM format) */
+    byMonth: Record<string, number>;
+    /** Average score */
+    averageScore: number;
+    /** Average scan duration in ms */
+    averageDuration: number;
+    /** Top findings */
+    topFindings: FindingSummary[];
+    /** Case study candidates count */
+    caseStudyCandidates: number;
+}
+/**
+ * Scan Registry for persistent tracking of all scans
+ */
+export declare class ScanRegistry {
+    private records;
+    private storagePath;
+    private loaded;
+    constructor(storagePath?: string);
+    /**
+     * Load registry from storage
+     */
+    load(): Promise<void>;
+    /**
+     * Save registry to storage
+     */
+    save(): Promise<void>;
+    /**
+     * Generate a unique scan ID
+     */
+    private generateScanId;
+    /**
+     * Hash a project path for matching
+     */
+    private hashProjectPath;
+    /**
+     * Record a new scan
+     */
+    recordScan(record: Omit<ScanRecord, "id" | "projectHash">): Promise<ScanRecord>;
+    /**
+     * Get a scan by ID
+     */
+    getScan(scanId: string): Promise<ScanRecord | undefined>;
+    /**
+     * Get scans for a project (by path or hash)
+     */
+    getScansForProject(projectPathOrHash: string): Promise<ScanRecord[]>;
+    /**
+     * Get scans for an organization
+     */
+    getScansForOrg(orgName: string): Promise<ScanRecord[]>;
+    /**
+     * Get recent scans
+     */
+    getRecentScans(limit?: number): Promise<ScanRecord[]>;
+    /**
+     * Get successful scans with high scores (case study candidates)
+     */
+    getCaseStudyCandidates(minScore?: number): Promise<ScanRecord[]>;
+    /**
+     * Get all unique organizations
+     */
+    getOrganizations(): Promise<string[]>;
+    /**
+     * Get analytics summary
+     */
+    getAnalytics(): Promise<RegistryAnalytics>;
+    /**
+     * Export registry to JSON
+     */
+    exportToJson(): Promise<string>;
+    /**
+     * Export analytics to JSON
+     */
+    exportAnalyticsToJson(): Promise<string>;
+    /**
+     * Get total scan count
+     */
+    getCount(): Promise<number>;
+    /**
+     * Clear all records (use with caution)
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Get the singleton registry instance
+ */
+export declare function getRegistry(storagePath?: string): ScanRegistry;
+/**
+ * Reset the singleton (for testing)
+ */
+export declare function resetRegistry(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/telemetry/registry.d.ts.map

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

package/dist/telemetry/registry.js

@@ -0,0 +1,297 @@
+/**
+ * Scan Registry Module
+ *
+ * Maintains a persistent registry of all scans for analytics,
+ * case study identification, and compliance auditing.
+ *
+ * @module telemetry/registry
+ */
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join, dirname } from "path";
+import { createHash } from "crypto";
+import { logger } from "../logger.js";
+// ============================================================================
+// Scan Registry
+// ============================================================================
+/**
+ * Scan Registry for persistent tracking of all scans
+ */
+export class ScanRegistry {
+    records = [];
+    storagePath;
+    loaded = false;
+    constructor(storagePath) {
+        this.storagePath =
+            storagePath ||
+                join(process.env.HOME || "/tmp", ".vaspera", "scan-registry.json");
+    }
+    /**
+     * Load registry from storage
+     */
+    async load() {
+        if (this.loaded)
+            return;
+        try {
+            const content = await readFile(this.storagePath, "utf-8");
+            const data = JSON.parse(content);
+            if (data.version !== 1) {
+                logger.warn("registry.version_mismatch", {
+                    expected: 1,
+                    actual: data.version,
+                });
+            }
+            this.records = data.records || [];
+            this.loaded = true;
+            logger.debug("registry.loaded", { recordCount: this.records.length });
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                this.records = [];
+                this.loaded = true;
+                logger.debug("registry.created_new");
+            }
+            else {
+                logger.error("registry.load_failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+        }
+    }
+    /**
+     * Save registry to storage
+     */
+    async save() {
+        const data = {
+            version: 1,
+            lastUpdated: new Date().toISOString(),
+            records: this.records,
+        };
+        await mkdir(dirname(this.storagePath), { recursive: true });
+        await writeFile(this.storagePath, JSON.stringify(data, null, 2));
+        logger.debug("registry.saved", { recordCount: this.records.length });
+    }
+    /**
+     * Generate a unique scan ID
+     */
+    generateScanId() {
+        const timestamp = Date.now().toString(36);
+        const random = Math.random().toString(36).slice(2, 8);
+        return `scan-${timestamp}-${random}`;
+    }
+    /**
+     * Hash a project path for matching
+     */
+    hashProjectPath(path) {
+        return createHash("sha256").update(path).digest("hex").slice(0, 16);
+    }
+    /**
+     * Record a new scan
+     */
+    async recordScan(record) {
+        await this.load();
+        const fullRecord = {
+            ...record,
+            id: this.generateScanId(),
+            projectHash: this.hashProjectPath(record.projectPath),
+        };
+        this.records.push(fullRecord);
+        await this.save();
+        logger.info("registry.scan_recorded", {
+            scanId: fullRecord.id,
+            level: fullRecord.level,
+            score: fullRecord.score,
+        });
+        return fullRecord;
+    }
+    /**
+     * Get a scan by ID
+     */
+    async getScan(scanId) {
+        await this.load();
+        return this.records.find((r) => r.id === scanId);
+    }
+    /**
+     * Get scans for a project (by path or hash)
+     */
+    async getScansForProject(projectPathOrHash) {
+        await this.load();
+        const hash = projectPathOrHash.length === 16
+            ? projectPathOrHash
+            : this.hashProjectPath(projectPathOrHash);
+        return this.records.filter((r) => r.projectHash === hash);
+    }
+    /**
+     * Get scans for an organization
+     */
+    async getScansForOrg(orgName) {
+        await this.load();
+        return this.records.filter((r) => r.orgName === orgName);
+    }
+    /**
+     * Get recent scans
+     */
+    async getRecentScans(limit = 50) {
+        await this.load();
+        return [...this.records]
+            .sort((a, b) => new Date(b.scanDate).getTime() - new Date(a.scanDate).getTime())
+            .slice(0, limit);
+    }
+    /**
+     * Get successful scans with high scores (case study candidates)
+     */
+    async getCaseStudyCandidates(minScore = 80) {
+        await this.load();
+        return this.records
+            .filter((r) => r.success &&
+            r.score !== undefined &&
+            r.score >= minScore &&
+            (r.caseStudyConsent === true || r.repoUrl !== undefined))
+            .sort((a, b) => (b.score || 0) - (a.score || 0));
+    }
+    /**
+     * Get all unique organizations
+     */
+    async getOrganizations() {
+        await this.load();
+        const orgs = new Set();
+        for (const record of this.records) {
+            if (record.orgName) {
+                orgs.add(record.orgName);
+            }
+        }
+        return Array.from(orgs).sort();
+    }
+    /**
+     * Get analytics summary
+     */
+    async getAnalytics() {
+        await this.load();
+        const byLevel = {
+            CERTIFIED: 0,
+            APPROVED: 0,
+            REVIEW_REQUIRED: 0,
+            BLOCKED: 0,
+        };
+        const byFramework = {};
+        const byScanner = {};
+        const byMonth = {};
+        const findingCounts = new Map();
+        let totalScore = 0;
+        let scoreCount = 0;
+        let totalDuration = 0;
+        let successfulScans = 0;
+        let failedScans = 0;
+        let caseStudyCandidates = 0;
+        for (const record of this.records) {
+            // Count success/failure
+            if (record.success) {
+                successfulScans++;
+            }
+            else {
+                failedScans++;
+            }
+            // Count by level
+            if (record.level) {
+                byLevel[record.level]++;
+            }
+            // Count by framework
+            for (const framework of record.frameworksAssessed) {
+                byFramework[framework] = (byFramework[framework] || 0) + 1;
+            }
+            // Count by scanner
+            for (const scanner of record.scannersRun) {
+                byScanner[scanner] = (byScanner[scanner] || 0) + 1;
+            }
+            // Count by month
+            const month = record.scanDate.slice(0, 7); // YYYY-MM
+            byMonth[month] = (byMonth[month] || 0) + 1;
+            // Accumulate score
+            if (record.score !== undefined) {
+                totalScore += record.score;
+                scoreCount++;
+            }
+            // Accumulate duration
+            totalDuration += record.duration;
+            // Count case study candidates
+            if (record.success && record.score !== undefined && record.score >= 80) {
+                if (record.caseStudyConsent || record.repoUrl) {
+                    caseStudyCandidates++;
+                }
+            }
+        }
+        // Calculate top findings (placeholder - would need finding-level data)
+        const topFindings = [];
+        return {
+            totalScans: this.records.length,
+            successfulScans,
+            failedScans,
+            byLevel,
+            byFramework,
+            byScanner,
+            byMonth,
+            averageScore: scoreCount > 0 ? Math.round(totalScore / scoreCount) : 0,
+            averageDuration: this.records.length > 0
+                ? Math.round(totalDuration / this.records.length)
+                : 0,
+            topFindings,
+            caseStudyCandidates,
+        };
+    }
+    /**
+     * Export registry to JSON
+     */
+    async exportToJson() {
+        await this.load();
+        return JSON.stringify({
+            exportedAt: new Date().toISOString(),
+            recordCount: this.records.length,
+            records: this.records,
+        }, null, 2);
+    }
+    /**
+     * Export analytics to JSON
+     */
+    async exportAnalyticsToJson() {
+        const analytics = await this.getAnalytics();
+        return JSON.stringify({
+            exportedAt: new Date().toISOString(),
+            analytics,
+        }, null, 2);
+    }
+    /**
+     * Get total scan count
+     */
+    async getCount() {
+        await this.load();
+        return this.records.length;
+    }
+    /**
+     * Clear all records (use with caution)
+     */
+    async clear() {
+        this.records = [];
+        await this.save();
+        logger.warn("registry.cleared");
+    }
+}
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+let _registry = null;
+/**
+ * Get the singleton registry instance
+ */
+export function getRegistry(storagePath) {
+    if (!_registry) {
+        _registry = new ScanRegistry(storagePath);
+    }
+    return _registry;
+}
+/**
+ * Reset the singleton (for testing)
+ */
+export function resetRegistry() {
+    _registry = null;
+}
+//# sourceMappingURL=registry.js.map

package/dist/telemetry/registry.js.map

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

package/dist/telemetry/usage.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Usage Telemetry Module
+ *
+ * Tracks scan events and usage patterns for analytics and case studies.
+ * All telemetry is opt-in and respects user privacy preferences.
+ *
+ * @module telemetry/usage
+ */
+import type { Severity, CertificationLevel } from "../certification/types.js";
+/**
+ * Telemetry configuration
+ */
+export interface TelemetryConfig {
+    /** Whether telemetry is enabled */
+    enabled: boolean;
+    /** API endpoint for telemetry events */
+    endpoint?: string;
+    /** Optional API key for authentication */
+    apiKey?: string;
+    /** Include repository URL (requires explicit opt-in) */
+    includeRepoUrl?: boolean;
+    /** Include organization name (requires explicit opt-in) */
+    includeOrgName?: boolean;
+    /** Include user email (requires explicit opt-in) */
+    includeUserEmail?: boolean;
+}
+/**
+ * Default telemetry configuration
+ */
+export declare const DEFAULT_TELEMETRY_CONFIG: TelemetryConfig;
+/**
+ * Types of telemetry events
+ */
+export type TelemetryEventType = "certification_started" | "certification_completed" | "certification_failed" | "finding_discovered" | "finding_resolved" | "scanner_run" | "badge_generated" | "sbom_generated" | "compliance_report_generated";
+/**
+ * Base telemetry event
+ */
+export interface BaseTelemetryEvent {
+    /** Event type */
+    eventType: TelemetryEventType;
+    /** ISO timestamp */
+    timestamp: string;
+    /** SHA256 hash of project path (anonymized) */
+    projectHash: string;
+    /** Vaspera version */
+    vasperaVersion: string;
+    /** Platform (darwin, linux, win32) */
+    platform: string;
+    /** Node.js version */
+    nodeVersion: string;
+}
+/**
+ * Event when a certification scan starts
+ */
+export interface CertificationStartedEvent extends BaseTelemetryEvent {
+    eventType: "certification_started";
+    /** Scanners being run */
+    scanners: string[];
+    /** Frameworks being assessed */
+    frameworks: string[];
+    /** Corpus size setting */
+    corpusSize?: string;
+}
+/**
+ * Event when a certification scan completes
+ */
+export interface CertificationCompletedEvent extends BaseTelemetryEvent {
+    eventType: "certification_completed";
+    /** Certification ID */
+    certificationId: string;
+    /** Achieved level */
+    level: CertificationLevel;
+    /** Overall score (0-100) */
+    score: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Findings count by severity */
+    severityCounts: Record<Severity, number>;
+    /** Total findings */
+    totalFindings: number;
+    /** Frameworks assessed */
+    frameworks: string[];
+    /** Optional: repository URL if user opted in */
+    repoUrl?: string;
+    /** Optional: organization name if user opted in */
+    orgName?: string;
+    /** Optional: user email if user opted in */
+    userEmail?: string;
+}
+/**
+ * Event when a certification scan fails
+ */
+export interface CertificationFailedEvent extends BaseTelemetryEvent {
+    eventType: "certification_failed";
+    /** Error message (sanitized) */
+    errorMessage: string;
+    /** Error category */
+    errorCategory: "scanner_error" | "config_error" | "timeout" | "unknown";
+    /** Duration before failure */
+    duration: number;
+}
+/**
+ * Event when a finding is discovered
+ */
+export interface FindingDiscoveredEvent extends BaseTelemetryEvent {
+    eventType: "finding_discovered";
+    /** Finding category */
+    category: string;
+    /** Severity level */
+    severity: Severity;
+    /** Scanner that found it */
+    scanner: string;
+    /** Rule/check ID */
+    ruleId?: string;
+}
+/**
+ * Event when a scanner completes
+ */
+export interface ScannerRunEvent extends BaseTelemetryEvent {
+    eventType: "scanner_run";
+    /** Scanner name */
+    scanner: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Number of findings */
+    findingsCount: number;
+    /** Whether it succeeded */
+    success: boolean;
+}
+/**
+ * Union of all telemetry events
+ */
+export type TelemetryEvent = CertificationStartedEvent | CertificationCompletedEvent | CertificationFailedEvent | FindingDiscoveredEvent | ScannerRunEvent;
+/**
+ * Initialize telemetry with configuration
+ */
+export declare function initTelemetry(config: Partial<TelemetryConfig>): void;
+/**
+ * Check if telemetry is enabled
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Hash a value for anonymization
+ */
+export declare function hashValue(value: string): string;
+/**
+ * Track a telemetry event
+ */
+export declare function trackEvent(event: Omit<TelemetryEvent, keyof BaseTelemetryEvent> & {
+    eventType: TelemetryEventType;
+    projectPath: string;
+}): Promise<void>;
+/**
+ * Flush buffered events to the telemetry endpoint
+ */
+export declare function flushEvents(): Promise<void>;
+/**
+ * Shutdown telemetry (flush remaining events)
+ */
+export declare function shutdownTelemetry(): Promise<void>;
+/**
+ * Track certification start
+ */
+export declare function trackCertificationStarted(projectPath: string, scanners: string[], frameworks: string[], corpusSize?: string): Promise<void>;
+/**
+ * Track certification completion
+ */
+export declare function trackCertificationCompleted(projectPath: string, certificationId: string, level: CertificationLevel, score: number, duration: number, severityCounts: Record<Severity, number>, totalFindings: number, frameworks: string[], optionalInfo?: {
+    repoUrl?: string;
+    orgName?: string;
+    userEmail?: string;
+}): Promise<void>;
+/**
+ * Track certification failure
+ */
+export declare function trackCertificationFailed(projectPath: string, errorMessage: string, errorCategory: CertificationFailedEvent["errorCategory"], duration: number): Promise<void>;
+/**
+ * Track a finding discovery
+ */
+export declare function trackFindingDiscovered(projectPath: string, category: string, severity: Severity, scanner: string, ruleId?: string): Promise<void>;
+/**
+ * Track a scanner run
+ */
+export declare function trackScannerRun(projectPath: string, scanner: string, duration: number, findingsCount: number, success: boolean): Promise<void>;
+export declare const telemetry: {
+    init: typeof initTelemetry;
+    isEnabled: typeof isTelemetryEnabled;
+    track: typeof trackEvent;
+    flush: typeof flushEvents;
+    shutdown: typeof shutdownTelemetry;
+    trackCertificationStarted: typeof trackCertificationStarted;
+    trackCertificationCompleted: typeof trackCertificationCompleted;
+    trackCertificationFailed: typeof trackCertificationFailed;
+    trackFindingDiscovered: typeof trackFindingDiscovered;
+    trackScannerRun: typeof trackScannerRun;
+};
+//# sourceMappingURL=usage.d.ts.map