@behavioral-contracts/verify-cli 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Core type definitions for behavioral contract verification
+ */
+export type Severity = 'error' | 'warning' | 'info';
+/**
+ * A precondition that must be true before calling a function
+ */
+export interface Precondition {
+    id: string;
+    description: string;
+    source: string;
+    severity: Severity;
+}
+/**
+ * A postcondition describing what happens after calling a function
+ */
+export interface Postcondition {
+    id: string;
+    condition: string;
+    returns?: string;
+    throws?: string;
+    required_handling?: string;
+    source: string;
+    severity: Severity;
+}
+/**
+ * An edge case documenting surprising but not incorrect behavior
+ */
+export interface EdgeCase {
+    id: string;
+    description: string;
+    source: string;
+    severity: 'warning' | 'info';
+}
+/**
+ * A function contract specifying behavioral expectations
+ */
+export interface FunctionContract {
+    name: string;
+    import_path: string;
+    description: string;
+    namespace?: string;
+    preconditions?: Precondition[];
+    postconditions?: Postcondition[];
+    edge_cases?: EdgeCase[];
+}
+/**
+ * Required event listener configuration
+ */
+export interface RequiredEventListener {
+    /** Event name (e.g., "error", "failed") */
+    event: string;
+    /** Whether this listener is required */
+    required: boolean;
+    /** Severity if missing (error, warning, info) */
+    severity?: 'error' | 'warning' | 'info';
+}
+/**
+ * Detection rules for identifying package usage in code
+ */
+export interface DetectionRules {
+    /** Class names used for instantiation (e.g., ["Octokit", "PrismaClient"]) */
+    class_names?: string[];
+    /** TypeScript type names used in declarations (e.g., ["Octokit", "AxiosInstance"]) */
+    type_names?: string[];
+    /** Factory method names (e.g., ["createClient", "create"]) */
+    factory_methods?: string[];
+    /** Patterns to match in await expressions (e.g., [".repos.", ".pulls."]) */
+    await_patterns?: string[];
+    /**
+     * If true, ONLY detect violations on tracked instances (no pattern fallback)
+     * Use this for packages with generic method names (mongoose, Prisma, TypeORM)
+     * to eliminate false positives from pattern matching
+     */
+    require_instance_tracking?: boolean;
+    /** Required event listeners for event-emitting classes */
+    required_event_listeners?: RequiredEventListener[];
+}
+/**
+ * A complete package contract
+ */
+export interface PackageContract {
+    package: string;
+    semver: string;
+    contract_version: string;
+    maintainer: string;
+    last_verified: string;
+    /** Quality/validation status (production, draft, in-development, deprecated) */
+    status?: 'production' | 'draft' | 'in-development' | 'deprecated';
+    deprecated?: boolean;
+    deprecated_reason?: string;
+    deprecated_date?: string;
+    /** Detection rules for analyzer integration */
+    detection?: DetectionRules;
+    functions: FunctionContract[];
+}
+/**
+ * A violation found in user code
+ */
+export interface Violation {
+    id: string;
+    severity: Severity;
+    file: string;
+    line: number;
+    column: number;
+    package: string;
+    function: string;
+    contract_clause: string;
+    description: string;
+    source_doc: string;
+    suggested_fix?: string;
+    code_snippet?: {
+        startLine: number;
+        endLine: number;
+        lines: Array<{
+            line: number;
+            content: string;
+            highlighted: boolean;
+        }>;
+    };
+}
+/**
+ * Summary statistics for a verification run
+ */
+export interface VerificationSummary {
+    total_violations: number;
+    error_count: number;
+    warning_count: number;
+    info_count: number;
+    passed: boolean;
+}
+/**
+ * Complete audit record produced by a verification run
+ */
+export interface AuditRecord {
+    tool: string;
+    tool_version: string;
+    corpus_version: string;
+    timestamp: string;
+    git_commit?: string;
+    git_branch?: string;
+    tsconfig: string;
+    packages_analyzed: string[];
+    contracts_applied: number;
+    files_analyzed: number;
+    violations: Violation[];
+    summary: VerificationSummary;
+}
+/**
+ * Location of a function call in the AST
+ */
+export interface CallSite {
+    file: string;
+    line: number;
+    column: number;
+    functionName: string;
+    packageName: string;
+}
+/**
+ * Result of analyzing a single call site
+ */
+export interface CallSiteAnalysis {
+    callSite: CallSite;
+    hasTryCatch: boolean;
+    hasPromiseCatch: boolean;
+    checksResponseExists: boolean;
+    checksStatusCode: boolean;
+    handledStatusCodes: number[];
+    hasRetryLogic: boolean;
+}
+/**
+ * Configuration options for the analyzer
+ */
+export interface AnalyzerConfig {
+    tsconfigPath: string;
+    corpusPath: string;
+    includePaths?: string[];
+    excludePaths?: string[];
+    severityThreshold?: Severity;
+    /** Whether to include test files in analysis (default: false) */
+    includeTests?: boolean;
+}
+/**
+ * Result of loading the corpus
+ */
+export interface CorpusLoadResult {
+    contracts: Map<string, PackageContract>;
+    errors: string[];
+    skipped?: Array<{
+        package: string;
+        status: string;
+        reason: string;
+    }>;
+}
+/**
+ * A package discovered in the project
+ */
+export interface DiscoveredPackage {
+    name: string;
+    version: string;
+    source: 'package.json' | 'import' | 'both';
+    hasContract: boolean;
+    contractVersion?: string;
+    usedIn: string[];
+}
+/**
+ * Result of package discovery scan
+ */
+export interface PackageDiscoveryResult {
+    total: number;
+    withContracts: number;
+    withoutContracts: number;
+    packages: DiscoveredPackage[];
+}
+/**
+ * Enhanced audit record with package discovery
+ */
+export interface EnhancedAuditRecord extends AuditRecord {
+    package_discovery: PackageDiscoveryResult;
+    violations_by_package: Record<string, {
+        total: number;
+        errors: number;
+        warnings: number;
+        info: number;
+        violations: Violation[];
+    }>;
+}
+/**
+ * A positive pattern (best practice) detected in code
+ */
+export interface PositivePattern {
+    id: string;
+    name: string;
+    description: string;
+    file: string;
+    line: number;
+    column: number;
+    category: 'configuration' | 'error-handling' | 'performance' | 'consistency';
+    benefit: string;
+    code_snippet?: {
+        startLine: number;
+        endLine: number;
+        lines: Array<{
+            line: number;
+            content: string;
+            highlighted: boolean;
+        }>;
+    };
+}
+/**
+ * React Query hook call detection
+ */
+export interface HookCall {
+    hookName: 'useQuery' | 'useMutation' | 'useInfiniteQuery' | 'QueryClient';
+    location: {
+        file: string;
+        line: number;
+        column: number;
+    };
+    returnValues: Map<string, string>;
+    options: {
+        onError?: boolean;
+        onMutate?: boolean;
+        onSuccess?: boolean;
+        retry?: 'default' | 'number' | 'boolean' | 'function';
+    };
+}
+/**
+ * Variable usage tracking for hook return values
+ */
+export interface VariableUsage {
+    variableName: string;
+    propertyName: string;
+    declaredAt: {
+        file: string;
+        line: number;
+    };
+    usedIn: {
+        conditionals: number;
+        jsxExpressions: number;
+        callbacks: number;
+    };
+}
+/**
+ * Analysis of error handling in React Query hooks
+ */
+export interface HookErrorHandling {
+    hasErrorStateCheck: boolean;
+    hasOnErrorCallback: boolean;
+    hasGlobalHandler: boolean;
+    errorCheckedBeforeDataAccess: boolean;
+    hasOptimisticUpdateRollback?: boolean;
+    retryAnalysis?: {
+        type: 'default' | 'number' | 'boolean' | 'function';
+        avoidsClientErrors: boolean;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core type definitions for behavioral contract verification
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@behavioral-contracts/verify-cli",
+  "version": "1.0.0",
+  "description": "CLI tool for verifying TypeScript code against behavioral contracts",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "verify-cli": "./dist/index.js",
+    "behavioral-contracts": "./dist/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "test:fixtures": "vitest run fixture-regression",
+    "test:fixtures:watch": "vitest fixture-regression",
+    "test:fixtures:generate": "node scripts/generate-expected-outputs.js",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "typescript",
+    "verification",
+    "behavioral-contracts",
+    "static-analysis",
+    "code-quality"
+  ],
+  "author": "Behavioral Contracts",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/behavioral-contracts/verify-cli.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@behavioral-contracts/corpus": "^1.0.0",
+    "ajv": "^8.12.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "glob": "^10.3.10",
+    "typescript": "^5.3.3",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "eslint": "^8.56.0",
+    "vitest": "^1.2.0"
+  }
+}