driftdetect-detectors 0.1.0

package/dist/api/response-envelope.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Response Envelope Detector - Response format pattern detection
+ *
+ * Detects response envelope patterns including:
+ * - Standard response envelope patterns ({ data, error, meta, success, message })
+ * - JSON:API format ({ data, errors, meta, links, included })
+ * - HAL format ({ _links, _embedded })
+ * - Pagination metadata ({ page, limit, total, hasMore, nextCursor })
+ * - Success/error response structures
+ * - Response.json() usage in Next.js
+ * - Express res.json() / res.send() patterns
+ *
+ * Flags violations:
+ * - Inconsistent response envelope structure across endpoints
+ * - Missing standard fields (data, error, success)
+ * - Mixing different response formats (JSON:API vs custom)
+ * - Raw data responses without envelope
+ * - Inconsistent pagination format
+ *
+ * @requirements 10.3 - THE API_Detector SHALL detect response envelope patterns ({ data, error, meta })
+ */
+import type { Violation, QuickFix, Language } from 'driftdetect-core';
+import { RegexDetector, type DetectionContext, type DetectionResult } from '../base/index.js';
+/**
+ * Types of response envelope formats detected
+ */
+export type ResponseEnvelopeFormat = 'standard' | 'json-api' | 'hal' | 'graphql' | 'custom' | 'direct';
+/**
+ * Types of response envelope patterns detected
+ */
+export type ResponseEnvelopePatternType = 'envelope-structure' | 'pagination-metadata' | 'error-response' | 'success-indicator' | 'nextjs-response' | 'express-response';
+/**
+ * Types of response envelope violations detected
+ */
+export type ResponseEnvelopeViolationType = 'inconsistent-envelope' | 'missing-data-field' | 'missing-error-field' | 'missing-success-indicator' | 'mixed-formats' | 'raw-data-response' | 'inconsistent-pagination' | 'missing-pagination';
+/**
+ * Pagination format types
+ */
+export type PaginationFormat = 'offset' | 'cursor' | 'page-based' | 'link-based' | 'mixed';
+/**
+ * Information about a detected response envelope pattern
+ */
+export interface ResponseEnvelopePatternInfo {
+    /** Type of pattern */
+    type: ResponseEnvelopePatternType;
+    /** Detected envelope format */
+    format: ResponseEnvelopeFormat;
+    /** File path */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+    /** The matched text */
+    matchedText: string;
+    /** Fields detected in the envelope */
+    fields?: string[] | undefined;
+    /** Pagination format (if detected) */
+    paginationFormat?: PaginationFormat | undefined;
+    /** Additional context */
+    context?: string | undefined;
+}
+/**
+ * Information about a detected response envelope violation
+ */
+export interface ResponseEnvelopeViolationInfo {
+    /** Type of violation */
+    type: ResponseEnvelopeViolationType;
+    /** File path */
+    file: string;
+    /** Line number (1-indexed) */
+    line: number;
+    /** Column number (1-indexed) */
+    column: number;
+    /** End line number (1-indexed) */
+    endLine: number;
+    /** End column number (1-indexed) */
+    endColumn: number;
+    /** The problematic value */
+    value: string;
+    /** Issue description */
+    issue: string;
+    /** Suggested fix */
+    suggestedFix?: string | undefined;
+    /** The full line content */
+    lineContent: string;
+}
+/**
+ * Analysis of response envelope patterns in a file
+ */
+export interface ResponseEnvelopeAnalysis {
+    /** Response envelope patterns found */
+    envelopePatterns: ResponseEnvelopePatternInfo[];
+    /** Violations detected */
+    violations: ResponseEnvelopeViolationInfo[];
+    /** Dominant envelope format in the file */
+    dominantFormat: ResponseEnvelopeFormat | null;
+    /** Pagination format used */
+    paginationFormat: PaginationFormat | null;
+    /** Whether file uses consistent envelope structure */
+    usesConsistentEnvelope: boolean;
+    /** Pattern adherence confidence */
+    patternAdherenceConfidence: number;
+}
+/**
+ * Standard envelope fields
+ */
+export declare const STANDARD_ENVELOPE_FIELDS: {
+    readonly data: readonly ["data", "result", "results", "payload", "body"];
+    readonly error: readonly ["error", "errors", "err", "errorMessage", "message"];
+    readonly meta: readonly ["meta", "metadata", "_meta", "info"];
+    readonly success: readonly ["success", "ok", "status", "isSuccess", "succeeded"];
+    readonly message: readonly ["message", "msg", "statusMessage", "description"];
+};
+/**
+ * JSON:API envelope fields
+ */
+export declare const JSON_API_FIELDS: readonly ["data", "errors", "meta", "links", "included", "jsonapi"];
+/**
+ * HAL format fields
+ */
+export declare const HAL_FIELDS: readonly ["_links", "_embedded"];
+/**
+ * GraphQL response fields
+ */
+export declare const GRAPHQL_FIELDS: readonly ["data", "errors", "extensions"];
+/**
+ * Pagination fields by format
+ * Note: Fields are organized to avoid overlap where possible
+ * - offset: uses limit/offset terminology
+ * - pageBased: uses pageSize/totalPages terminology
+ * - cursor: uses cursor/hasMore terminology
+ * - linkBased: uses next/prev/first/last links
+ */
+export declare const PAGINATION_FIELDS: {
+    readonly offset: readonly ["limit", "offset", "total", "totalCount", "count"];
+    readonly cursor: readonly ["cursor", "nextCursor", "prevCursor", "hasMore", "hasNext", "hasPrev", "endCursor", "startCursor"];
+    readonly pageBased: readonly ["pageSize", "totalPages", "currentPage", "perPage"];
+    readonly linkBased: readonly ["next", "prev", "first", "last", "self"];
+    readonly common: readonly ["page"];
+};
+/**
+ * Response patterns for Next.js
+ */
+export declare const NEXTJS_RESPONSE_PATTERNS: readonly [RegExp, RegExp, RegExp];
+/**
+ * Response patterns for Express
+ */
+export declare const EXPRESS_RESPONSE_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp];
+/**
+ * Generic response object patterns
+ */
+export declare const RESPONSE_OBJECT_PATTERNS: readonly [RegExp, RegExp, RegExp];
+/**
+ * Error response patterns
+ */
+export declare const ERROR_RESPONSE_PATTERNS: readonly [RegExp, RegExp, RegExp, RegExp];
+/**
+ * File patterns to exclude from detection
+ */
+export declare const EXCLUDED_FILE_PATTERNS: RegExp[];
+/**
+ * Check if a file should be excluded from detection
+ */
+export declare function shouldExcludeFile(filePath: string): boolean;
+/**
+ * Extract field names from an object literal string
+ */
+export declare function extractFieldNames(objectContent: string): string[];
+/**
+ * Detect the envelope format from fields
+ */
+export declare function detectEnvelopeFormat(fields: string[]): ResponseEnvelopeFormat;
+/**
+ * Detect pagination format from fields
+ */
+export declare function detectPaginationFormat(fields: string[]): PaginationFormat | null;
+/**
+ * Check if fields indicate a list/collection response
+ */
+export declare function isListResponse(fields: string[], content: string): boolean;
+/**
+ * Detect Next.js response patterns
+ */
+export declare function detectNextjsResponses(content: string, file: string): ResponseEnvelopePatternInfo[];
+/**
+ * Detect Express response patterns
+ */
+export declare function detectExpressResponses(content: string, file: string): ResponseEnvelopePatternInfo[];
+/**
+ * Detect generic response object patterns
+ */
+export declare function detectResponseObjects(content: string, file: string): ResponseEnvelopePatternInfo[];
+/**
+ * Detect error response patterns
+ */
+export declare function detectErrorResponses(content: string, file: string): ResponseEnvelopePatternInfo[];
+/**
+ * Detect pagination metadata patterns
+ */
+export declare function detectPaginationPatterns(content: string, file: string): ResponseEnvelopePatternInfo[];
+/**
+ * Detect inconsistent envelope structure violations
+ */
+export declare function detectInconsistentEnvelopeViolations(patterns: ResponseEnvelopePatternInfo[], file: string): ResponseEnvelopeViolationInfo[];
+/**
+ * Detect missing standard fields violations
+ */
+export declare function detectMissingFieldViolations(patterns: ResponseEnvelopePatternInfo[], file: string): ResponseEnvelopeViolationInfo[];
+/**
+ * Detect raw data response violations
+ */
+export declare function detectRawDataViolations(patterns: ResponseEnvelopePatternInfo[], content: string, file: string): ResponseEnvelopeViolationInfo[];
+/**
+ * Detect inconsistent pagination violations
+ */
+export declare function detectInconsistentPaginationViolations(patterns: ResponseEnvelopePatternInfo[], file: string): ResponseEnvelopeViolationInfo[];
+/**
+ * Analyze response envelope patterns in a file
+ */
+export declare function analyzeResponseEnvelope(content: string, file: string): ResponseEnvelopeAnalysis;
+/**
+ * Detector for response envelope patterns
+ *
+ * Identifies response envelope patterns and flags violations of consistency.
+ *
+ * @requirements 10.3 - THE API_Detector SHALL detect response envelope patterns ({ data, error, meta })
+ */
+export declare class ResponseEnvelopeDetector extends RegexDetector {
+    readonly id = "api/response-envelope";
+    readonly category: "api";
+    readonly subcategory = "response-envelope";
+    readonly name = "Response Envelope Detector";
+    readonly description = "Detects response envelope patterns and flags inconsistencies";
+    readonly supportedLanguages: Language[];
+    /**
+     * Detect response envelope patterns and violations
+     */
+    detect(context: DetectionContext): Promise<DetectionResult>;
+    /**
+     * Create a Violation from ResponseEnvelopeViolationInfo
+     */
+    private createViolation;
+    /**
+     * Get explanation for a violation type
+     */
+    private getExplanation;
+    /**
+     * Create a quick fix for a violation
+     */
+    private createQuickFixForViolation;
+    /**
+     * Generate a quick fix for a violation
+     */
+    generateQuickFix(violation: Violation): QuickFix | null;
+}
+/**
+ * Create a new ResponseEnvelopeDetector instance
+ */
+export declare function createResponseEnvelopeDetector(): ResponseEnvelopeDetector;
+//# sourceMappingURL=response-envelope.d.ts.map

package/dist/api/response-envelope.d.ts.map

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