scanwarp 0.2.0 → 0.3.1

package/dist/dev/analysis-engine.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Analysis engine for scanwarp dev.
+ *
+ * Runs analyzers on incoming traces, deduplicates results so each unique
+ * issue is shown only once, and prints "resolved" when an issue goes away.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalysisEngine = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+const analyzers_js_1 = require("./analyzers.js");
+class AnalysisEngine {
+    analyzers;
+    issues = new Map();
+    /** Track which issues fired in the most recent analysis pass per trace */
+    lastTraceIssueKeys = new Set();
+    constructor(analyzers) {
+        this.analyzers = analyzers ?? analyzers_js_1.defaultAnalyzers;
+    }
+    /**
+     * Analyze a complete trace (all spans with the same trace_id).
+     * Returns new/changed results that should be printed.
+     */
+    analyzeTrace(spans) {
+        if (spans.length === 0)
+            return;
+        const now = Date.now();
+        const currentKeys = new Set();
+        // Run all analyzers
+        for (const analyzer of this.analyzers) {
+            const results = analyzer.analyze(spans);
+            for (const result of results) {
+                const key = this.makeKey(result);
+                currentKeys.add(key);
+                const existing = this.issues.get(key);
+                if (existing) {
+                    existing.hitCount++;
+                    existing.lastSeen = now;
+                    // Don't re-print — already shown
+                }
+                else {
+                    // New issue — track and print
+                    const tracked = {
+                        result,
+                        key,
+                        hitCount: 1,
+                        firstSeen: now,
+                        lastSeen: now,
+                        printed: true,
+                        resolved: false,
+                    };
+                    this.issues.set(key, tracked);
+                    this.printResult(result);
+                }
+            }
+        }
+        // Check for resolved issues — issues that were active in the previous trace
+        // from the same route but are no longer firing
+        for (const [key, issue] of this.issues) {
+            if (this.lastTraceIssueKeys.has(key) &&
+                !currentKeys.has(key) &&
+                !issue.resolved) {
+                issue.resolved = true;
+                this.printResolved(issue);
+            }
+        }
+        this.lastTraceIssueKeys = currentKeys;
+    }
+    /** Generate a dedup key from rule + core message content */
+    makeKey(result) {
+        // Strip numbers/counts from the message so "executed 23 times" and "executed 24 times"
+        // don't create separate entries
+        const normalizedMessage = result.message
+            .replace(/\d+\s*times/g, 'N times')
+            .replace(/\d+ms/g, 'Nms');
+        return `${result.rule}:${normalizedMessage}`;
+    }
+    /** Print a new analysis result inline */
+    printResult(result) {
+        const icon = result.severity === 'error'
+            ? chalk_1.default.red('!')
+            : result.severity === 'warning'
+                ? chalk_1.default.yellow('!')
+                : chalk_1.default.blue('i');
+        const severityColor = result.severity === 'error'
+            ? chalk_1.default.red
+            : result.severity === 'warning'
+                ? chalk_1.default.yellow
+                : chalk_1.default.blue;
+        const tag = severityColor(`[${result.rule}]`);
+        console.log(`\n           ${icon} ${tag} ${result.message}`);
+        if (result.suggestion) {
+            console.log(chalk_1.default.gray(`             → ${result.suggestion}`));
+        }
+    }
+    /** Print when an issue is resolved */
+    printResolved(issue) {
+        const tag = chalk_1.default.green(`[${issue.result.rule}]`);
+        // Truncate the message for the resolved line
+        const shortMsg = issue.result.message.length > 60
+            ? issue.result.message.substring(0, 60) + '...'
+            : issue.result.message;
+        console.log(`\n           ${chalk_1.default.green('✓')} ${tag} ${chalk_1.default.green('Resolved:')} ${chalk_1.default.gray(shortMsg)}`);
+    }
+    /** Get count of currently active (unresolved) issues */
+    get activeIssueCount() {
+        let count = 0;
+        for (const issue of this.issues.values()) {
+            if (!issue.resolved)
+                count++;
+        }
+        return count;
+    }
+    /** Get all active (unresolved) issues with full detail */
+    getActiveIssues() {
+        const results = [];
+        for (const issue of this.issues.values()) {
+            if (!issue.resolved) {
+                results.push(issue.result);
+            }
+        }
+        return results;
+    }
+    /** Get all tracked issues (for session summary) */
+    getSummary() {
+        let active = 0;
+        let resolved = 0;
+        const byRule = new Map();
+        for (const issue of this.issues.values()) {
+            if (issue.resolved) {
+                resolved++;
+            }
+            else {
+                active++;
+            }
+            const count = byRule.get(issue.result.rule) || 0;
+            byRule.set(issue.result.rule, count + 1);
+        }
+        return { total: this.issues.size, active, resolved, byRule };
+    }
+}
+exports.AnalysisEngine = AnalysisEngine;

package/dist/dev/analyzers/schema-drift.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * Schema drift detection for API routes.
+ *
+ * Infers a structural schema from JSON responses, stores baselines per
+ * route+method, and detects drift: removed fields, type changes, new fields,
+ * and null→non-null (or vice-versa) transitions.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaTracker = void 0;
+exports.inferSchema = inferSchema;
+exports.compareSchemas = compareSchemas;
+const chalk_1 = __importDefault(require("chalk"));
+// ─── Schema inference ───
+function inferSchema(value) {
+    if (value === null || value === undefined) {
+        return { kind: 'null' };
+    }
+    if (typeof value === 'boolean')
+        return { kind: 'boolean' };
+    if (typeof value === 'number')
+        return { kind: 'number' };
+    if (typeof value === 'string')
+        return { kind: 'string' };
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return { kind: 'array', items: null };
+        }
+        // Infer from first element (representative sample)
+        return { kind: 'array', items: inferSchema(value[0]) };
+    }
+    if (typeof value === 'object') {
+        const fields = new Map();
+        for (const [key, val] of Object.entries(value)) {
+            fields.set(key, inferSchema(val));
+        }
+        return { kind: 'object', fields };
+    }
+    return { kind: 'string' }; // fallback
+}
+// ─── Schema comparison ───
+function compareSchemas(baseline, current, path = '$') {
+    const diffs = [];
+    // Handle nullable wrapper
+    const baseKind = baseline.kind === 'nullable' ? baseline.inner.kind : baseline.kind;
+    const currKind = current.kind === 'nullable' ? current.inner.kind : current.kind;
+    const baseNode = baseline.kind === 'nullable' ? baseline.inner : baseline;
+    const currNode = current.kind === 'nullable' ? current.inner : current;
+    // Null status changes
+    const baseIsNullable = baseline.kind === 'null' || baseline.kind === 'nullable';
+    const currIsNullable = current.kind === 'null' || current.kind === 'nullable';
+    if (baseIsNullable !== currIsNullable && baseKind === currKind) {
+        if (baseIsNullable && !currIsNullable) {
+            diffs.push({
+                type: 'null_changed',
+                path,
+                detail: `was nullable, now always ${currKind}`,
+            });
+        }
+        else if (!baseIsNullable && currIsNullable) {
+            diffs.push({
+                type: 'null_changed',
+                path,
+                detail: `was ${baseKind}, now nullable`,
+            });
+        }
+    }
+    // Type change (different base kinds)
+    if (baseKind !== currKind && baseline.kind !== 'null' && current.kind !== 'null') {
+        diffs.push({
+            type: 'type_changed',
+            path,
+            detail: `was ${baseKind}, now ${currKind}`,
+        });
+        return diffs; // No point comparing children if types differ
+    }
+    // Object comparison
+    if (baseNode.kind === 'object' && currNode.kind === 'object') {
+        // Removed fields
+        for (const [key, baseFieldSchema] of baseNode.fields) {
+            if (!currNode.fields.has(key)) {
+                diffs.push({
+                    type: 'removed',
+                    path: `${path}.${key}`,
+                    detail: `field removed (was ${schemaKindLabel(baseFieldSchema)})`,
+                });
+            }
+            else {
+                // Recurse into shared fields
+                const currFieldSchema = currNode.fields.get(key);
+                diffs.push(...compareSchemas(baseFieldSchema, currFieldSchema, `${path}.${key}`));
+            }
+        }
+        // New fields
+        for (const [key, currFieldSchema] of currNode.fields) {
+            if (!baseNode.fields.has(key)) {
+                diffs.push({
+                    type: 'added',
+                    path: `${path}.${key}`,
+                    detail: `new field (${schemaKindLabel(currFieldSchema)})`,
+                });
+            }
+        }
+    }
+    // Array comparison — compare item schemas
+    if (baseNode.kind === 'array' && currNode.kind === 'array') {
+        if (baseNode.items && currNode.items) {
+            diffs.push(...compareSchemas(baseNode.items, currNode.items, `${path}[]`));
+        }
+    }
+    return diffs;
+}
+function schemaKindLabel(node) {
+    switch (node.kind) {
+        case 'object': return 'object';
+        case 'array': return node.items ? `${schemaKindLabel(node.items)}[]` : 'array';
+        case 'nullable': return `${schemaKindLabel(node.inner)}?`;
+        default: return node.kind;
+    }
+}
+// ─── Schema Tracker ───
+class SchemaTracker {
+    /** Key: "METHOD route" (e.g. "GET /api/products") */
+    baselines = new Map();
+    /** Number of consecutive responses with new schema needed to auto-accept */
+    static AUTO_ACCEPT_COUNT = 3;
+    /**
+     * Process a response body from a route check.
+     * Only call for 2xx responses on API routes.
+     * Returns diffs if schema drift is detected, empty array otherwise.
+     */
+    processResponse(route, method, body) {
+        const key = `${method} ${route}`;
+        const currentSchema = inferSchema(body);
+        const existing = this.baselines.get(key);
+        if (!existing) {
+            // First response — store as baseline
+            this.baselines.set(key, {
+                schema: currentSchema,
+                consecutiveMatches: 1,
+                pendingSchema: null,
+                pendingMatches: 0,
+            });
+            return [];
+        }
+        // Compare against baseline
+        const diffs = compareSchemas(existing.schema, currentSchema);
+        if (diffs.length === 0) {
+            // Matches baseline — reset any pending schema
+            existing.consecutiveMatches++;
+            existing.pendingSchema = null;
+            existing.pendingMatches = 0;
+            return [];
+        }
+        // Schema differs from baseline
+        if (existing.pendingSchema) {
+            // Check if it matches the pending schema
+            const pendingDiffs = compareSchemas(existing.pendingSchema, currentSchema);
+            if (pendingDiffs.length === 0) {
+                existing.pendingMatches++;
+                if (existing.pendingMatches >= SchemaTracker.AUTO_ACCEPT_COUNT) {
+                    // Auto-accept: the new schema has been seen enough times
+                    existing.schema = existing.pendingSchema;
+                    existing.consecutiveMatches = existing.pendingMatches;
+                    existing.pendingSchema = null;
+                    existing.pendingMatches = 0;
+                    return []; // Silently accept
+                }
+                // Still pending — return diffs against original baseline
+                return diffs;
+            }
+            // Different from both baseline and pending — start new pending
+            existing.pendingSchema = currentSchema;
+            existing.pendingMatches = 1;
+            return diffs;
+        }
+        // First time seeing a different schema — start pending
+        existing.pendingSchema = currentSchema;
+        existing.pendingMatches = 1;
+        return diffs;
+    }
+    /** Reset the baseline for routes associated with a changed file */
+    resetForRoutes(routes) {
+        for (const route of routes) {
+            // Reset all methods for this route
+            for (const key of this.baselines.keys()) {
+                if (key.endsWith(` ${route}`)) {
+                    this.baselines.delete(key);
+                }
+            }
+        }
+    }
+    /** Get active baselines (for API status) */
+    getBaselineCount() {
+        return this.baselines.size;
+    }
+    /** Print schema drift warnings */
+    static printDrift(route, method, diffs) {
+        if (diffs.length === 0)
+            return;
+        const time = new Date().toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
+        console.log('');
+        console.log(chalk_1.default.yellow(`   ${time}  ⚠  ${method} ${route}  — schema changed`));
+        let hasBreakingChange = false;
+        for (const diff of diffs) {
+            if (diff.type === 'removed') {
+                console.log(chalk_1.default.red(`           Removed field: ${diff.path} (${diff.detail})`));
+                hasBreakingChange = true;
+            }
+            else if (diff.type === 'type_changed') {
+                console.log(chalk_1.default.yellow(`           Type changed: ${diff.path} (${diff.detail})`));
+                hasBreakingChange = true;
+            }
+            else if (diff.type === 'added') {
+                console.log(chalk_1.default.cyan(`           New field: ${diff.path} (${diff.detail})`));
+            }
+            else if (diff.type === 'null_changed') {
+                console.log(chalk_1.default.blue(`           Null changed: ${diff.path} (${diff.detail})`));
+                hasBreakingChange = true;
+            }
+        }
+        if (hasBreakingChange) {
+            console.log(chalk_1.default.yellow(`           ⚠ This may break frontend consumers of this API`));
+        }
+    }
+}
+exports.SchemaTracker = SchemaTracker;

package/dist/dev/analyzers.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * Real-time trace analyzers for scanwarp dev.
+ *
+ * Each analyzer inspects spans from a single trace and returns
+ * zero or more analysis results (warnings, errors, suggestions).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultAnalyzers = exports.slowExternalCallDetector = exports.missingErrorHandlingDetector = exports.unhandledErrorDetector = exports.slowQueryDetector = exports.nPlusOneDetector = void 0;
+// ─── Helpers ───
+function getParentSpan(span, spans) {
+    if (!span.parent_span_id)
+        return undefined;
+    return spans.find((s) => s.span_id === span.parent_span_id);
+}
+function isDbSpan(span) {
+    return span.attributes['db.system'] !== undefined;
+}
+function isHttpClientSpan(span) {
+    return (span.kind === 'CLIENT' &&
+        (span.attributes['http.url'] !== undefined ||
+            span.attributes['url.full'] !== undefined));
+}
+function getHttpUrl(span) {
+    const url = span.attributes['http.url'] || span.attributes['url.full'];
+    return typeof url === 'string' ? url : String(url ?? '');
+}
+function getDbStatement(span) {
+    const stmt = span.attributes['db.statement'];
+    return typeof stmt === 'string' ? stmt : '';
+}
+/** Normalize a SQL statement by replacing literal values with ? placeholders */
+function normalizeQuery(sql) {
+    return sql
+        .replace(/'[^']*'/g, '?') // string literals
+        .replace(/\b\d+\b/g, '?') // numeric literals
+        .replace(/\s+/g, ' ') // collapse whitespace
+        .trim();
+}
+function truncate(str, max) {
+    return str.length > max ? str.substring(0, max) + '...' : str;
+}
+function getErrorMessage(span) {
+    // Try exception event first
+    const exceptionEvent = span.events.find((e) => e.name === 'exception');
+    const exceptionMsg = exceptionEvent?.attributes?.['exception.message'];
+    if (typeof exceptionMsg === 'string')
+        return exceptionMsg;
+    // Fall back to status message
+    if (span.status_message)
+        return span.status_message;
+    return 'Unknown error';
+}
+// ─── Analyzer implementations ───
+/**
+ * N+1 Query Detector
+ *
+ * Groups database spans by normalized query pattern within a single trace.
+ * If the same pattern appears 5+ times, flags it as an N+1.
+ */
+exports.nPlusOneDetector = {
+    name: 'n-plus-one',
+    analyze(spans) {
+        const results = [];
+        // Group DB spans by normalized statement
+        const queryCounts = new Map();
+        for (const span of spans) {
+            if (!isDbSpan(span))
+                continue;
+            const stmt = getDbStatement(span);
+            if (!stmt)
+                continue;
+            const normalized = normalizeQuery(stmt);
+            const existing = queryCounts.get(normalized);
+            if (existing) {
+                existing.count++;
+            }
+            else {
+                queryCounts.set(normalized, { count: 1, raw: stmt });
+            }
+        }
+        for (const [pattern, { count, raw }] of queryCounts) {
+            if (count >= 5) {
+                results.push({
+                    severity: 'warning',
+                    rule: 'n-plus-one',
+                    message: `N+1 query detected: '${truncate(pattern, 80)}' executed ${count} times`,
+                    detail: `Full query: ${truncate(raw, 200)}`,
+                    suggestion: 'Use a batch query or JOIN instead of querying in a loop',
+                });
+            }
+        }
+        return results;
+    },
+};
+/**
+ * Slow Database Query Detector
+ *
+ * Flags any database span over 500ms.
+ */
+exports.slowQueryDetector = {
+    name: 'slow-query',
+    analyze(spans) {
+        const results = [];
+        for (const span of spans) {
+            if (!isDbSpan(span))
+                continue;
+            if (span.duration_ms <= 500)
+                continue;
+            const stmt = getDbStatement(span);
+            const dbSystem = String(span.attributes['db.system'] || 'database');
+            results.push({
+                severity: 'warning',
+                rule: 'slow-query',
+                message: `Slow ${dbSystem} query: ${truncate(stmt || span.operation_name, 100)} (${span.duration_ms}ms)`,
+                suggestion: 'Consider adding an index or optimizing this query',
+            });
+        }
+        return results;
+    },
+};
+/**
+ * Unhandled Error Detector
+ *
+ * Detects when a span has ERROR status and its parent also has ERROR status,
+ * indicating the error propagated up without being caught.
+ */
+exports.unhandledErrorDetector = {
+    name: 'unhandled-error',
+    analyze(spans) {
+        const results = [];
+        for (const span of spans) {
+            if (span.status_code !== 'ERROR')
+                continue;
+            const parent = getParentSpan(span, spans);
+            if (!parent || parent.status_code !== 'ERROR')
+                continue;
+            // Skip HTTP client spans — they have their own analyzer
+            if (isHttpClientSpan(span))
+                continue;
+            const errorMsg = getErrorMessage(span);
+            results.push({
+                severity: 'error',
+                rule: 'unhandled-error',
+                message: `Unhandled error in ${span.operation_name}: ${truncate(errorMsg, 100)}`,
+                suggestion: 'Add error handling (try/catch) around this operation',
+            });
+        }
+        return results;
+    },
+};
+/**
+ * Missing Error Handling on External Calls
+ *
+ * When an HTTP client span fails and the parent span also has ERROR status,
+ * the external call failure wasn't handled gracefully.
+ */
+exports.missingErrorHandlingDetector = {
+    name: 'missing-error-handling',
+    analyze(spans) {
+        const results = [];
+        for (const span of spans) {
+            if (!isHttpClientSpan(span))
+                continue;
+            if (span.status_code !== 'ERROR')
+                continue;
+            const parent = getParentSpan(span, spans);
+            if (!parent || parent.status_code !== 'ERROR')
+                continue;
+            const url = getHttpUrl(span);
+            // Extract just the host for cleaner output
+            let host = url;
+            try {
+                host = new URL(url).host;
+            }
+            catch {
+                // keep raw url
+            }
+            results.push({
+                severity: 'error',
+                rule: 'missing-error-handling',
+                message: `External API call to ${host} failed with no error handling`,
+                detail: `URL: ${truncate(url, 150)}`,
+                suggestion: 'Wrap this API call in try/catch and handle failures gracefully',
+            });
+        }
+        return results;
+    },
+};
+/**
+ * Slow External API Call
+ *
+ * Flags any HTTP client span over 2 seconds.
+ */
+exports.slowExternalCallDetector = {
+    name: 'slow-external-call',
+    analyze(spans) {
+        const results = [];
+        for (const span of spans) {
+            if (!isHttpClientSpan(span))
+                continue;
+            if (span.duration_ms <= 2000)
+                continue;
+            const url = getHttpUrl(span);
+            let host = url;
+            try {
+                host = new URL(url).host;
+            }
+            catch {
+                // keep raw url
+            }
+            results.push({
+                severity: 'warning',
+                rule: 'slow-external-call',
+                message: `Slow external call to ${host}: ${span.duration_ms}ms`,
+                detail: `URL: ${truncate(url, 150)}`,
+                suggestion: 'Consider adding a timeout, caching the response, or making it async',
+            });
+        }
+        return results;
+    },
+};
+// ─── All built-in analyzers ───
+exports.defaultAnalyzers = [
+    exports.nPlusOneDetector,
+    exports.slowQueryDetector,
+    exports.unhandledErrorDetector,
+    exports.missingErrorHandlingDetector,
+    exports.slowExternalCallDetector,
+];