@behavioral-contracts/verify-cli 1.0.0

package/dist/analyzers/react-query-analyzer.js.map

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

package/dist/analyzers/return-value-analyzer.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Return Value Analyzer
+ * Detects unprotected error checks on function return values
+ *
+ * This analyzer tracks:
+ * 1. Variable assignments from contract functions
+ * 2. Error checks on those return values (null, false, error properties)
+ * 3. Whether those checks are protected by try-catch
+ *
+ * Related: dev-notes/analyzer-enhancement/RETURN_VALUE_RESEARCH.md
+ */
+import * as ts from 'typescript';
+import type { PackageContract, Postcondition } from '../types.js';
+export interface ReturnValueCheck {
+    /** Variable name holding the return value */
+    variableName: string;
+    /** Package the function belongs to */
+    packageName: string;
+    /** Function name that returned the value */
+    functionName: string;
+    /** Postcondition that requires error handling */
+    postcondition: Postcondition;
+    /** AST node where variable was declared */
+    declarationNode: ts.Node;
+    /** AST node where error check occurs (if any) */
+    checkNode?: ts.Node;
+    /** Whether the error check is protected by try-catch */
+    isProtected: boolean;
+}
+export declare class ReturnValueAnalyzer {
+    private sourceFile;
+    private contracts;
+    private trackedReturnValues;
+    constructor(sourceFile: ts.SourceFile, contracts: Map<string, PackageContract>, _typeChecker: ts.TypeChecker);
+    /**
+     * Analyzes a function scope for unprotected return value checks
+     */
+    analyze(functionNode: ts.Node): ReturnValueCheck[];
+    /**
+     * Finds variable declarations that assign return values from contract functions
+     */
+    private findReturnValueDeclarations;
+    /**
+     * Extracts contract function information from a call expression
+     */
+    private extractContractFunctionCall;
+    /**
+     * Finds error check on a tracked return value
+     * Looks for patterns like: if (!result), if (result.error), if (!result.success)
+     */
+    private findErrorCheck;
+    /**
+     * Checks if a node is protected by try-catch
+     */
+    private isNodeProtected;
+    /**
+     * Checks if child is a descendant of parent node
+     */
+    private isDescendantOf;
+}
+//# sourceMappingURL=return-value-analyzer.d.ts.map

package/dist/analyzers/return-value-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-value-analyzer.d.ts","sourceRoot":"","sources":["../../src/analyzers/return-value-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,aAAa,EAAE,aAAa,CAAC;IAC7B,2CAA2C;IAC3C,eAAe,EAAE,EAAE,CAAC,IAAI,CAAC;IACzB,iDAAiD;IACjD,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IACpB,wDAAwD;IACxD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,SAAS,CAA+B;IAIhD,OAAO,CAAC,mBAAmB,CAKZ;gBAGb,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,YAAY,EAAE,EAAE,CAAC,WAAW;IAO9B;;OAEG;IACH,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,IAAI,GAAG,gBAAgB,EAAE;IA6ClD;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAwBnC;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAuDnC;;;OAGG;IACH,OAAO,CAAC,cAAc;IA6DtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAyBvB;;OAEG;IACH,OAAO,CAAC,cAAc;CAYvB"}

package/dist/analyzers/return-value-analyzer.js

@@ -0,0 +1,225 @@
+/**
+ * Return Value Analyzer
+ * Detects unprotected error checks on function return values
+ *
+ * This analyzer tracks:
+ * 1. Variable assignments from contract functions
+ * 2. Error checks on those return values (null, false, error properties)
+ * 3. Whether those checks are protected by try-catch
+ *
+ * Related: dev-notes/analyzer-enhancement/RETURN_VALUE_RESEARCH.md
+ */
+import * as ts from 'typescript';
+export class ReturnValueAnalyzer {
+    sourceFile;
+    contracts;
+    // private typeChecker: ts.TypeChecker; // Reserved for future type-aware detection
+    // Track return values that need error checking
+    trackedReturnValues = new Map();
+    constructor(sourceFile, contracts, _typeChecker // Reserved for future type-aware detection
+    ) {
+        this.sourceFile = sourceFile;
+        this.contracts = contracts;
+        // this.typeChecker = typeChecker; // Reserved for future type-aware detection
+    }
+    /**
+     * Analyzes a function scope for unprotected return value checks
+     */
+    analyze(functionNode) {
+        const violations = [];
+        // Step 1: Find all variable declarations from contract functions
+        this.findReturnValueDeclarations(functionNode);
+        // Step 2: For each tracked return value, find error checks
+        for (const [varName, info] of this.trackedReturnValues.entries()) {
+            const errorCheck = this.findErrorCheck(varName, functionNode);
+            if (!errorCheck) {
+                // No error check found - violation
+                violations.push({
+                    variableName: varName,
+                    packageName: info.packageName,
+                    functionName: info.functionName,
+                    postcondition: info.postcondition,
+                    declarationNode: info.declarationNode,
+                    isProtected: false,
+                });
+            }
+            else {
+                // Error check found - verify it's in try-catch
+                const isProtected = this.isNodeProtected(errorCheck, functionNode);
+                if (!isProtected) {
+                    // Error check exists but not in try-catch - violation
+                    violations.push({
+                        variableName: varName,
+                        packageName: info.packageName,
+                        functionName: info.functionName,
+                        postcondition: info.postcondition,
+                        declarationNode: info.declarationNode,
+                        checkNode: errorCheck,
+                        isProtected: false,
+                    });
+                }
+            }
+        }
+        // Clear for next function
+        this.trackedReturnValues.clear();
+        return violations;
+    }
+    /**
+     * Finds variable declarations that assign return values from contract functions
+     */
+    findReturnValueDeclarations(scope) {
+        const visit = (node) => {
+            // Pattern: const result = validator.normalizeEmail(email)
+            if (ts.isVariableDeclaration(node) && node.initializer) {
+                const callInfo = this.extractContractFunctionCall(node.initializer);
+                if (callInfo) {
+                    const varName = node.name.getText(this.sourceFile);
+                    this.trackedReturnValues.set(varName, {
+                        packageName: callInfo.packageName,
+                        functionName: callInfo.functionName,
+                        postcondition: callInfo.postcondition,
+                        declarationNode: node,
+                    });
+                }
+            }
+            // Continue visiting children
+            ts.forEachChild(node, visit);
+        };
+        visit(scope);
+    }
+    /**
+     * Extracts contract function information from a call expression
+     */
+    extractContractFunctionCall(node) {
+        if (!ts.isCallExpression(node)) {
+            return null;
+        }
+        let functionName = null;
+        let objectName = null;
+        // Pattern: validator.normalizeEmail(...)
+        if (ts.isPropertyAccessExpression(node.expression)) {
+            functionName = node.expression.name.text;
+            if (ts.isIdentifier(node.expression.expression)) {
+                objectName = node.expression.expression.text;
+            }
+        }
+        // Pattern: normalizeEmail(...) - direct call
+        if (ts.isIdentifier(node.expression)) {
+            functionName = node.expression.text;
+        }
+        if (!functionName) {
+            return null;
+        }
+        // Check if this function belongs to any contract
+        for (const [packageName, contract] of this.contracts.entries()) {
+            // Simple heuristic: if objectName matches package name or is similar
+            const packageMatches = objectName === packageName ||
+                objectName === packageName.split('/').pop() ||
+                objectName === packageName.replace(/@/g, '').replace(/\//g, '-');
+            if (packageMatches || !objectName) {
+                // Check if function exists in contract
+                const func = contract.functions?.find(f => f.name === functionName);
+                if (func && func.postconditions && func.postconditions.length > 0) {
+                    return {
+                        packageName,
+                        functionName,
+                        postcondition: func.postconditions[0], // Use first postcondition
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Finds error check on a tracked return value
+     * Looks for patterns like: if (!result), if (result.error), if (!result.success)
+     */
+    findErrorCheck(varName, scope) {
+        let checkNode = null;
+        const visit = (node) => {
+            // Pattern: if (!result) { ... }
+            if (ts.isIfStatement(node)) {
+                const condition = node.expression;
+                // Check for: !variable
+                if (ts.isPrefixUnaryExpression(condition) &&
+                    condition.operator === ts.SyntaxKind.ExclamationToken &&
+                    ts.isIdentifier(condition.operand) &&
+                    condition.operand.text === varName) {
+                    checkNode = node;
+                    return;
+                }
+                // Check for: variable (boolean check)
+                if (ts.isIdentifier(condition) && condition.text === varName) {
+                    checkNode = node;
+                    return;
+                }
+                // Check for: !variable.property
+                if (ts.isPrefixUnaryExpression(condition) &&
+                    condition.operator === ts.SyntaxKind.ExclamationToken &&
+                    ts.isPropertyAccessExpression(condition.operand) &&
+                    ts.isIdentifier(condition.operand.expression) &&
+                    condition.operand.expression.text === varName) {
+                    checkNode = node;
+                    return;
+                }
+                // Check for: variable.error or variable.success
+                if (ts.isPropertyAccessExpression(condition) &&
+                    ts.isIdentifier(condition.expression) &&
+                    condition.expression.text === varName) {
+                    checkNode = node;
+                    return;
+                }
+            }
+            // Pattern: result || defaultValue
+            if (ts.isBinaryExpression(node) &&
+                node.operatorToken.kind === ts.SyntaxKind.BarBarToken &&
+                ts.isIdentifier(node.left) &&
+                node.left.text === varName) {
+                checkNode = node;
+                return;
+            }
+            // Continue searching if not found
+            if (!checkNode) {
+                ts.forEachChild(node, visit);
+            }
+        };
+        visit(scope);
+        return checkNode;
+    }
+    /**
+     * Checks if a node is protected by try-catch
+     */
+    isNodeProtected(node, functionScope) {
+        let current = node;
+        // Walk up the AST until we find a try block or reach function boundary
+        while (current && current !== functionScope) {
+            const parent = current.parent;
+            if (!parent) {
+                break;
+            }
+            // Check if we're inside a try block
+            if (ts.isTryStatement(parent)) {
+                // Check if current node is within the try block (not catch or finally)
+                if (parent.tryBlock === current || this.isDescendantOf(node, parent.tryBlock)) {
+                    return true;
+                }
+            }
+            current = parent;
+        }
+        return false;
+    }
+    /**
+     * Checks if child is a descendant of parent node
+     */
+    isDescendantOf(child, parent) {
+        let current = child;
+        while (current) {
+            if (current === parent) {
+                return true;
+            }
+            current = current.parent;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=return-value-analyzer.js.map

package/dist/analyzers/return-value-analyzer.js.map

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

package/dist/code-snippet.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Code Snippet Extraction Module
+ *
+ * Extracts code snippets around violation locations with context lines.
+ */
+export interface CodeSnippet {
+    lines: CodeLine[];
+    startLine: number;
+    endLine: number;
+}
+export interface CodeLine {
+    lineNumber: number;
+    content: string;
+    isViolation: boolean;
+}
+/**
+ * Extracts a code snippet from a file around a specific line
+ *
+ * @param filePath - Path to the source file
+ * @param violationLine - Line number where the violation occurred
+ * @param contextLines - Number of lines to show before and after (default: 4)
+ * @returns Code snippet with context
+ */
+export declare function extractCodeSnippet(filePath: string, violationLine: number, contextLines?: number): Promise<CodeSnippet | null>;
+/**
+ * Formats a code snippet for terminal display
+ *
+ * @param snippet - Code snippet to format
+ * @param maxLineLength - Maximum length of a line (truncate longer lines)
+ * @returns Formatted string array
+ */
+export declare function formatSnippetForTerminal(snippet: CodeSnippet, maxLineLength?: number): string[];
+/**
+ * Formats a code snippet for JSON export
+ *
+ * @param snippet - Code snippet to format
+ * @returns Object suitable for JSON serialization
+ */
+export declare function formatSnippetForJSON(snippet: CodeSnippet): {
+    startLine: number;
+    endLine: number;
+    lines: Array<{
+        line: number;
+        content: string;
+        highlighted: boolean;
+    }>;
+};
+//# sourceMappingURL=code-snippet.d.ts.map

package/dist/code-snippet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-snippet.d.ts","sourceRoot":"","sources":["../src/code-snippet.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,YAAY,GAAE,MAAU,GACvB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA8B7B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,aAAa,GAAE,MAAY,GAC1B,MAAM,EAAE,CAmBV;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,GAAG;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACvE,CAUA"}

package/dist/code-snippet.js

@@ -0,0 +1,84 @@
+/**
+ * Code Snippet Extraction Module
+ *
+ * Extracts code snippets around violation locations with context lines.
+ */
+import * as fs from 'fs/promises';
+/**
+ * Extracts a code snippet from a file around a specific line
+ *
+ * @param filePath - Path to the source file
+ * @param violationLine - Line number where the violation occurred
+ * @param contextLines - Number of lines to show before and after (default: 4)
+ * @returns Code snippet with context
+ */
+export async function extractCodeSnippet(filePath, violationLine, contextLines = 4) {
+    try {
+        // Read the entire file
+        const content = await fs.readFile(filePath, 'utf-8');
+        const lines = content.split('\n');
+        // Calculate range (1-indexed line numbers)
+        const startLine = Math.max(1, violationLine - contextLines);
+        const endLine = Math.min(lines.length, violationLine + contextLines);
+        // Extract lines (convert to 0-indexed for array access)
+        const snippetLines = [];
+        for (let i = startLine; i <= endLine; i++) {
+            const lineContent = lines[i - 1]; // Convert to 0-indexed
+            snippetLines.push({
+                lineNumber: i,
+                content: lineContent,
+                isViolation: i === violationLine,
+            });
+        }
+        return {
+            lines: snippetLines,
+            startLine,
+            endLine,
+        };
+    }
+    catch (error) {
+        // File might not be accessible, return null
+        return null;
+    }
+}
+/**
+ * Formats a code snippet for terminal display
+ *
+ * @param snippet - Code snippet to format
+ * @param maxLineLength - Maximum length of a line (truncate longer lines)
+ * @returns Formatted string array
+ */
+export function formatSnippetForTerminal(snippet, maxLineLength = 120) {
+    const output = [];
+    const maxLineNumWidth = String(snippet.endLine).length;
+    for (const line of snippet.lines) {
+        const lineNum = String(line.lineNumber).padStart(maxLineNumWidth, ' ');
+        let content = line.content;
+        // Truncate long lines
+        if (content.length > maxLineLength) {
+            content = content.substring(0, maxLineLength - 3) + '...';
+        }
+        // Add line prefix
+        const prefix = line.isViolation ? '>' : ' ';
+        output.push(`${prefix} ${lineNum} | ${content}`);
+    }
+    return output;
+}
+/**
+ * Formats a code snippet for JSON export
+ *
+ * @param snippet - Code snippet to format
+ * @returns Object suitable for JSON serialization
+ */
+export function formatSnippetForJSON(snippet) {
+    return {
+        startLine: snippet.startLine,
+        endLine: snippet.endLine,
+        lines: snippet.lines.map(line => ({
+            line: line.lineNumber,
+            content: line.content,
+            highlighted: line.isViolation,
+        })),
+    };
+}
+//# sourceMappingURL=code-snippet.js.map

package/dist/code-snippet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-snippet.js","sourceRoot":"","sources":["../src/code-snippet.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAclC;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,aAAqB,EACrB,eAAuB,CAAC;IAExB,IAAI,CAAC;QACH,uBAAuB;QACvB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAElC,2CAA2C;QAC3C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC;QAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC;QAErE,wDAAwD;QACxD,MAAM,YAAY,GAAe,EAAE,CAAC;QACpC,KAAK,IAAI,CAAC,GAAG,SAAS,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;YAC1C,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,uBAAuB;YACzD,YAAY,CAAC,IAAI,CAAC;gBAChB,UAAU,EAAE,CAAC;gBACb,OAAO,EAAE,WAAW;gBACpB,WAAW,EAAE,CAAC,KAAK,aAAa;aACjC,CAAC,CAAC;QACL,CAAC;QAED,OAAO;YACL,KAAK,EAAE,YAAY;YACnB,SAAS;YACT,OAAO;SACR,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,4CAA4C;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAoB,EACpB,gBAAwB,GAAG;IAE3B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;IAEvD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;QACvE,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAE3B,sBAAsB;QACtB,IAAI,OAAO,CAAC,MAAM,GAAG,aAAa,EAAE,CAAC;YACnC,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,aAAa,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;QAC5D,CAAC;QAED,kBAAkB;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,OAAO,MAAM,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAoB;IAKvD,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAChC,IAAI,EAAE,IAAI,CAAC,UAAU;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/corpus-loader.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Corpus Loader - loads and validates behavioral contract files
+ */
+import type { PackageContract, CorpusLoadResult } from './types.js';
+export interface LoadCorpusOptions {
+    includeDrafts?: boolean;
+    includeDeprecated?: boolean;
+    includeInDevelopment?: boolean;
+}
+/**
+ * Loads all behavioral contracts from the corpus directory
+ */
+export declare function loadCorpus(corpusPath: string, options?: LoadCorpusOptions): Promise<CorpusLoadResult>;
+/**
+ * Loads a single contract file (for testing)
+ */
+export declare function loadContractFile(filePath: string): PackageContract;
+/**
+ * Validates a contract object against the schema
+ */
+export declare function validateContract(contract: PackageContract, schemaPath: string): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Gets the list of packages that have contracts in the corpus
+ */
+export declare function getAvailablePackages(corpusPath: string): string[];
+/**
+ * Finds which packages from the corpus are actually used in a TypeScript project
+ */
+export declare function findUsedPackages(projectPackageJson: string, availableContracts: Map<string, PackageContract>): string[];
+//# sourceMappingURL=corpus-loader.d.ts.map

package/dist/corpus-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"corpus-loader.d.ts","sourceRoot":"","sources":["../src/corpus-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKpE,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC,CAyG3B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAGlE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,UAAU,EAAE,MAAM,GACjB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAatC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAWjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GAC/C,MAAM,EAAE,CAeV"}

package/dist/corpus-loader.js

@@ -0,0 +1,155 @@
+/**
+ * Corpus Loader - loads and validates behavioral contract files
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { glob } from 'glob';
+import * as YAML from 'yaml';
+import AjvModule from 'ajv';
+// Handle ESM/CJS interop for Ajv
+const Ajv = AjvModule.default || AjvModule;
+/**
+ * Loads all behavioral contracts from the corpus directory
+ */
+export async function loadCorpus(corpusPath, options = {}) {
+    const contracts = new Map();
+    const errors = [];
+    const skipped = [];
+    // Find all contract.yaml files
+    const contractFiles = await glob('**/contract.yaml', {
+        cwd: path.join(corpusPath, 'packages'),
+        absolute: true,
+    });
+    if (contractFiles.length === 0) {
+        errors.push(`No contract files found in ${corpusPath}/packages`);
+        return { contracts, errors };
+    }
+    // Load JSON Schema for validation
+    const schemaPath = path.join(corpusPath, 'schema', 'contract.schema.json');
+    let schema;
+    try {
+        const schemaContent = fs.readFileSync(schemaPath, 'utf-8');
+        schema = JSON.parse(schemaContent);
+    }
+    catch (err) {
+        errors.push(`Failed to load schema from ${schemaPath}: ${err}`);
+        return { contracts, errors };
+    }
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    const validate = ajv.compile(schema);
+    // Load and validate each contract
+    for (const filePath of contractFiles) {
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            const contract = YAML.parse(content);
+            // Get contract status (default to 'production' if not specified)
+            const status = contract.status || 'production';
+            // Skip in-development contracts silently (to avoid errors during development)
+            if (status === 'in-development' && !options.includeInDevelopment) {
+                skipped.push({
+                    package: contract.package || path.basename(path.dirname(filePath)),
+                    status: 'in-development',
+                    reason: 'Contract is in development (use --include-drafts to include)'
+                });
+                continue;
+            }
+            // Validate against JSON Schema
+            const valid = validate(contract);
+            if (!valid) {
+                // If it's in-development and validation fails, skip silently
+                if (status === 'in-development') {
+                    skipped.push({
+                        package: contract.package || path.basename(path.dirname(filePath)),
+                        status: 'in-development',
+                        reason: 'Contract validation failed (in-development)'
+                    });
+                    continue;
+                }
+                const validationErrors = validate.errors
+                    ?.map((err) => `  ${err.instancePath} ${err.message}`)
+                    .join('\n');
+                errors.push(`Invalid contract ${filePath}:\n${validationErrors}`);
+                continue;
+            }
+            // Filter by status
+            if (status === 'draft' && !options.includeDrafts) {
+                skipped.push({
+                    package: contract.package,
+                    status: 'draft',
+                    reason: 'Draft contract excluded (use --include-drafts to include)'
+                });
+                continue;
+            }
+            if (status === 'deprecated' && !options.includeDeprecated) {
+                skipped.push({
+                    package: contract.package,
+                    status: 'deprecated',
+                    reason: 'Deprecated contract excluded (use --include-deprecated to include)'
+                });
+                continue;
+            }
+            // Check for duplicate package names
+            if (contracts.has(contract.package)) {
+                errors.push(`Duplicate contract for package "${contract.package}" found at ${filePath}`);
+                continue;
+            }
+            contracts.set(contract.package, contract);
+        }
+        catch (err) {
+            errors.push(`Failed to load contract ${filePath}: ${err}`);
+        }
+    }
+    return { contracts, errors, skipped };
+}
+/**
+ * Loads a single contract file (for testing)
+ */
+export function loadContractFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return YAML.parse(content);
+}
+/**
+ * Validates a contract object against the schema
+ */
+export function validateContract(contract, schemaPath) {
+    const schemaContent = fs.readFileSync(schemaPath, 'utf-8');
+    const schema = JSON.parse(schemaContent);
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    const validate = ajv.compile(schema);
+    const valid = validate(contract);
+    const errors = valid
+        ? []
+        : (validate.errors?.map((err) => `${err.instancePath} ${err.message}`) || []);
+    return { valid, errors };
+}
+/**
+ * Gets the list of packages that have contracts in the corpus
+ */
+export function getAvailablePackages(corpusPath) {
+    const packagesDir = path.join(corpusPath, 'packages');
+    if (!fs.existsSync(packagesDir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(packagesDir, { withFileTypes: true })
+        .filter(dirent => dirent.isDirectory())
+        .map(dirent => dirent.name);
+}
+/**
+ * Finds which packages from the corpus are actually used in a TypeScript project
+ */
+export function findUsedPackages(projectPackageJson, availableContracts) {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(projectPackageJson, 'utf-8'));
+        const dependencies = {
+            ...packageJson.dependencies,
+            ...packageJson.devDependencies,
+        };
+        return Array.from(availableContracts.keys()).filter(packageName => packageName in dependencies);
+    }
+    catch (err) {
+        console.warn(`Could not read ${projectPackageJson}: ${err}`);
+        return [];
+    }
+}
+//# sourceMappingURL=corpus-loader.js.map