driftdetect-core 0.1.1 → 0.1.3

package/dist/types/contracts.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Contract type definitions
+ *
+ * Contracts represent the relationship between backend API endpoints
+ * and frontend TypeScript types. They enable detection of mismatches
+ * between what the backend returns and what the frontend expects.
+ *
+ * @requirements - Track BE↔FE type mismatches (the "silent failure killer")
+ */
+/**
+ * Status of a contract in the system
+ *
+ * - discovered: Contract found but not yet reviewed
+ * - verified: Contract verified as correct
+ * - mismatch: Contract has field mismatches
+ * - ignored: Contract explicitly ignored by user
+ */
+export type ContractStatus = 'discovered' | 'verified' | 'mismatch' | 'ignored';
+/**
+ * A field in an API response or TypeScript type
+ */
+export interface ContractField {
+    /** Field name */
+    name: string;
+    /** Field type (e.g., 'string', 'number', 'boolean', 'object', 'array') */
+    type: string;
+    /** Whether the field is optional */
+    optional: boolean;
+    /** Whether the field is nullable */
+    nullable: boolean;
+    /** Nested fields (for objects) */
+    children?: ContractField[];
+    /** Array element type (for arrays) */
+    arrayType?: string;
+    /** Line number where field is defined */
+    line?: number;
+}
+/**
+ * A mismatch between backend and frontend field definitions
+ */
+export interface FieldMismatch {
+    /** Field name/path (e.g., 'user.email' for nested) */
+    fieldPath: string;
+    /** Type of mismatch */
+    mismatchType: 'missing_in_frontend' | 'missing_in_backend' | 'type_mismatch' | 'optionality_mismatch' | 'nullability_mismatch';
+    /** Backend field definition (if exists) */
+    backendField?: ContractField;
+    /** Frontend field definition (if exists) */
+    frontendField?: ContractField;
+    /** Human-readable description of the mismatch */
+    description: string;
+    /** Severity of the mismatch */
+    severity: 'error' | 'warning' | 'info';
+}
+/**
+ * HTTP methods
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Backend endpoint definition extracted from source code
+ */
+export interface BackendEndpoint {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Route path (e.g., '/api/users/{id}') */
+    path: string;
+    /** Normalized path for matching (e.g., '/api/users/:id') */
+    normalizedPath: string;
+    /** File where endpoint is defined */
+    file: string;
+    /** Line number of endpoint definition */
+    line: number;
+    /** Response fields extracted from the endpoint */
+    responseFields: ContractField[];
+    /** Request body fields (for POST/PUT/PATCH) */
+    requestFields?: ContractField[];
+    /** Response type name (if using a schema/model) */
+    responseTypeName?: string;
+    /** Framework detected (e.g., 'fastapi', 'express', 'flask') */
+    framework: string;
+}
+/**
+ * Frontend API call definition extracted from source code
+ */
+export interface FrontendApiCall {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Route path (e.g., '/api/users/${id}') */
+    path: string;
+    /** Normalized path for matching */
+    normalizedPath: string;
+    /** File where API call is made */
+    file: string;
+    /** Line number of API call */
+    line: number;
+    /** TypeScript type used for the response */
+    responseType?: string;
+    /** Fields expected in the response */
+    responseFields: ContractField[];
+    /** Request body type */
+    requestType?: string;
+    /** Request body fields */
+    requestFields?: ContractField[];
+    /** Library used (e.g., 'fetch', 'axios', 'react-query') */
+    library: string;
+}
+/**
+ * Confidence information for a contract
+ */
+export interface ContractConfidence {
+    /** Overall confidence score (0.0 to 1.0) */
+    score: number;
+    /** Confidence level */
+    level: 'high' | 'medium' | 'low' | 'uncertain';
+    /** How confident we are in the endpoint matching */
+    matchConfidence: number;
+    /** How confident we are in the field extraction */
+    fieldExtractionConfidence: number;
+}
+/**
+ * Metadata for a contract
+ */
+export interface ContractMetadata {
+    /** ISO timestamp when contract was first detected */
+    firstSeen: string;
+    /** ISO timestamp when contract was last seen */
+    lastSeen: string;
+    /** ISO timestamp when contract was verified (if verified) */
+    verifiedAt?: string;
+    /** User who verified the contract */
+    verifiedBy?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Custom metadata */
+    custom?: Record<string, unknown>;
+}
+/**
+ * A contract between a backend endpoint and frontend type
+ *
+ * This is the primary contract type used throughout the system.
+ */
+export interface Contract {
+    /** Unique contract identifier */
+    id: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Normalized endpoint path */
+    endpoint: string;
+    /** Backend endpoint definition */
+    backend: BackendEndpoint;
+    /** Frontend API call definitions (may have multiple calls to same endpoint) */
+    frontend: FrontendApiCall[];
+    /** Field mismatches detected */
+    mismatches: FieldMismatch[];
+    /** Contract status */
+    status: ContractStatus;
+    /** Confidence information */
+    confidence: ContractConfidence;
+    /** Contract metadata */
+    metadata: ContractMetadata;
+}
+/**
+ * Stored contract format (used in JSON files)
+ */
+export interface StoredContract {
+    /** Unique contract ID */
+    id: string;
+    /** HTTP method */
+    method: HttpMethod;
+    /** Normalized endpoint path */
+    endpoint: string;
+    /** Backend endpoint definition */
+    backend: BackendEndpoint;
+    /** Frontend API call definitions */
+    frontend: FrontendApiCall[];
+    /** Field mismatches detected */
+    mismatches: FieldMismatch[];
+    /** Confidence information */
+    confidence: ContractConfidence;
+    /** Contract metadata */
+    metadata: ContractMetadata;
+}
+/**
+ * Format of a contract file stored in .drift/contracts/
+ */
+export interface ContractFile {
+    /** Schema version */
+    version: string;
+    /** Contract status this file contains */
+    status: ContractStatus;
+    /** Contracts in this file */
+    contracts: StoredContract[];
+    /** ISO timestamp of last update */
+    lastUpdated: string;
+    /** Checksum for integrity verification */
+    checksum?: string;
+}
+/**
+ * Current schema version for contract files
+ */
+export declare const CONTRACT_FILE_VERSION = "1.0.0";
+/**
+ * Query options for filtering contracts
+ */
+export interface ContractQuery {
+    /** Filter by contract IDs */
+    ids?: string[];
+    /** Filter by status */
+    status?: ContractStatus | ContractStatus[];
+    /** Filter by HTTP method */
+    method?: HttpMethod | HttpMethod[];
+    /** Filter by endpoint path (partial match) */
+    endpoint?: string;
+    /** Filter contracts with mismatches */
+    hasMismatches?: boolean;
+    /** Filter by minimum mismatch count */
+    minMismatches?: number;
+    /** Filter by backend file */
+    backendFile?: string;
+    /** Filter by frontend file */
+    frontendFile?: string;
+    /** Filter by minimum confidence score */
+    minConfidence?: number;
+    /** Search in endpoint path */
+    search?: string;
+}
+/**
+ * Sort options for contract queries
+ */
+export interface ContractSortOptions {
+    /** Field to sort by */
+    field: 'endpoint' | 'method' | 'mismatchCount' | 'confidence' | 'firstSeen' | 'lastSeen';
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Complete query options for contracts
+ */
+export interface ContractQueryOptions {
+    /** Filter criteria */
+    filter?: ContractQuery;
+    /** Sort options */
+    sort?: ContractSortOptions;
+    /** Pagination */
+    pagination?: {
+        offset?: number;
+        limit?: number;
+    };
+}
+/**
+ * Result of a contract query
+ */
+export interface ContractQueryResult {
+    /** Matching contracts */
+    contracts: Contract[];
+    /** Total count (before pagination) */
+    total: number;
+    /** Whether there are more results */
+    hasMore: boolean;
+    /** Query execution time in milliseconds */
+    executionTime: number;
+}
+/**
+ * Statistics about contracts
+ */
+export interface ContractStats {
+    /** Total number of contracts */
+    totalContracts: number;
+    /** Contracts by status */
+    byStatus: Record<ContractStatus, number>;
+    /** Contracts by HTTP method */
+    byMethod: Record<HttpMethod, number>;
+    /** Total number of mismatches */
+    totalMismatches: number;
+    /** Mismatches by type */
+    mismatchesByType: Record<FieldMismatch['mismatchType'], number>;
+    /** ISO timestamp of last update */
+    lastUpdated: string;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/types/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/types/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAMhF;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IAEb,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IAEb,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAElB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAElB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAE3B,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAElB,uBAAuB;IACvB,YAAY,EAAE,qBAAqB,GAAG,oBAAoB,GAAG,eAAe,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;IAE/H,2CAA2C;IAC3C,YAAY,CAAC,EAAE,aAAa,CAAC;IAE7B,4CAA4C;IAC5C,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IAEpB,+BAA+B;IAC/B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;CACxC;AAMD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,MAAM,EAAE,UAAU,CAAC;IAEnB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IAEb,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IAEvB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,cAAc,EAAE,aAAa,EAAE,CAAC;IAEhC,+CAA+C;IAC/C,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC;IAEhC,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,MAAM,EAAE,UAAU,CAAC;IAEnB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IAEb,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IAEvB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,sCAAsC;IACtC,cAAc,EAAE,aAAa,EAAE,CAAC;IAEhC,wBAAwB;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,0BAA0B;IAC1B,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC;IAEhC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IAEd,uBAAuB;IACvB,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,WAAW,CAAC;IAE/C,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IAExB,mDAAmD;IACnD,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAElB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IAEjB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IAEX,kBAAkB;IAClB,MAAM,EAAE,UAAU,CAAC;IAEnB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IAEjB,kCAAkC;IAClC,OAAO,EAAE,eAAe,CAAC;IAEzB,+EAA+E;IAC/E,QAAQ,EAAE,eAAe,EAAE,CAAC;IAE5B,gCAAgC;IAChC,UAAU,EAAE,aAAa,EAAE,CAAC;IAE5B,sBAAsB;IACtB,MAAM,EAAE,cAAc,CAAC;IAEvB,6BAA6B;IAC7B,UAAU,EAAE,kBAAkB,CAAC;IAE/B,wBAAwB;IACxB,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IAEX,kBAAkB;IAClB,MAAM,EAAE,UAAU,CAAC;IAEnB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IAEjB,kCAAkC;IAClC,OAAO,EAAE,eAAe,CAAC;IAEzB,oCAAoC;IACpC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAE5B,gCAAgC;IAChC,UAAU,EAAE,aAAa,EAAE,CAAC;IAE5B,6BAA6B;IAC7B,UAAU,EAAE,kBAAkB,CAAC;IAE/B,wBAAwB;IACxB,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAEhB,yCAAyC;IACzC,MAAM,EAAE,cAAc,CAAC;IAEvB,6BAA6B;IAC7B,SAAS,EAAE,cAAc,EAAE,CAAC;IAE5B,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IAEpB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAM7C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IAEf,uBAAuB;IACvB,MAAM,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC;IAE3C,4BAA4B;IAC5B,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IAEnC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,uCAAuC;IACvC,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,6BAA6B;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uBAAuB;IACvB,KAAK,EAAE,UAAU,GAAG,QAAQ,GAAG,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;IAEzF,qBAAqB;IACrB,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,sBAAsB;IACtB,MAAM,CAAC,EAAE,aAAa,CAAC;IAEvB,mBAAmB;IACnB,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAE3B,iBAAiB;IACjB,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yBAAyB;IACzB,SAAS,EAAE,QAAQ,EAAE,CAAC;IAEtB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IAEd,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;IAEjB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IAEvB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IAEzC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAErC,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IAExB,yBAAyB;IACzB,gBAAgB,EAAE,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IAEhE,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/contracts.js

@@ -0,0 +1,14 @@
+/**
+ * Contract type definitions
+ *
+ * Contracts represent the relationship between backend API endpoints
+ * and frontend TypeScript types. They enable detection of mismatches
+ * between what the backend returns and what the frontend expects.
+ *
+ * @requirements - Track BE↔FE type mismatches (the "silent failure killer")
+ */
+/**
+ * Current schema version for contract files
+ */
+export const CONTRACT_FILE_VERSION = '1.0.0';
+//# sourceMappingURL=contracts.js.map

package/dist/types/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/types/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoRH;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "driftdetect-core",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Core pattern detection and analysis engine for Drift",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/gfernald/drift"
+    "url": "https://github.com/dadbodgeoff/drift"
   },
-  "keywords": ["architecture", "drift", "patterns", "code-quality", "static-analysis"],
+  "keywords": [
+    "architecture",
+    "drift",
+    "patterns",
+    "code-quality",
+    "static-analysis"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",