opencroc 0.1.7 → 0.4.0

package/dist/index.d.ts

@@ -50,6 +50,12 @@ interface ModuleDefinition {
     modelDir: string;
     controllerDir: string;
     associationFile?: string;
+    /** Controller file paths (resolved) */
+    controllerPaths?: string[];
+    /** Service file paths (for inferring related tables) */
+    servicePaths?: string[];
+    /** Table name prefix for this module (e.g. 'user_') */
+    tablePrefix?: string;
 }
 interface RouteEntry {
     method: string;
@@ -68,7 +74,7 @@ interface FieldSchema {
 }
 interface TableSchema {
     tableName: string;
-    className: string;
+    className?: string;
     fields: FieldSchema[];
     indexes?: IndexSchema[];
 }
@@ -79,23 +85,42 @@ interface IndexSchema {
 }
 interface ForeignKeyRelation {
     sourceTable: string;
+    sourceField: string;
     targetTable: string;
-    sourceColumn: string;
-    targetColumn: string;
-    type: 'belongsTo' | 'hasMany' | 'hasOne' | 'belongsToMany';
+    targetField: string;
+    cardinality: '1:N' | 'N:1' | '1:1';
+    isCrossModule?: boolean;
 }
 interface ApiEndpoint {
     method: string;
     path: string;
-    handler: string;
-    module: string;
-    params?: string[];
-    bodyFields?: string[];
+    pathParams: string[];
+    queryParams: string[];
+    bodyFields: string[];
+    responseFields: string[];
+    relatedTables: string[];
+    description: string;
 }
 interface ApiDependency {
     from: ApiEndpoint;
     to: ApiEndpoint;
-    reason: string;
+    paramMapping: Record<string, string>;
+}
+interface DirectedAcyclicGraph {
+    nodes: string[];
+    edges: Array<{
+        from: string;
+        to: string;
+        label?: string;
+    }>;
+}
+interface ApiChainAnalysisResult {
+    moduleName: string;
+    endpoints: ApiEndpoint[];
+    dependencies: ApiDependency[];
+    dag: DirectedAcyclicGraph;
+    hasCycles: boolean;
+    cycleWarnings: string[];
 }
 interface ERDiagramResult {
     tables: TableSchema[];
@@ -137,12 +162,17 @@ interface ChainFailureResult {
     failedStep: number;
     error: string;
     rootCause?: string;
+    category?: string;
+    confidence?: number;
     impactedChains: string[];
+    errorChainPath?: string;
 }
 interface ImpactReport {
     affectedModules: string[];
     affectedChains: string[];
     affectedEndpoints: ApiEndpoint[];
+    affectedTables: string[];
+    severity: 'critical' | 'high' | 'medium' | 'low';
     mermaidText: string;
 }
 interface ValidationError {
@@ -151,6 +181,18 @@ interface ValidationError {
     message: string;
     severity: 'error' | 'warning';
 }
+interface SelfHealingResult {
+    iterations: number;
+    fixed: string[];
+    remaining: string[];
+    totalTokensUsed: number;
+}
+interface FixOutcome {
+    success: boolean;
+    scope: 'config-only' | 'config-and-source';
+    fixedItems: string[];
+    rolledBack: boolean;
+}
 interface BackendAdapter {
     name: string;
     parseModels(dir: string): Promise<TableSchema[]>;
@@ -189,23 +231,52 @@ declare function defineConfig(config: OpenCrocConfig): OpenCrocConfig;
 interface Pipeline {
     run(steps?: PipelineStep[]): Promise<PipelineRunResult>;
 }
-declare function createPipeline(_config: OpenCrocConfig): Pipeline;
+declare function createPipeline(config: OpenCrocConfig): Pipeline;
 
 interface ModelParser {
-    parseFile(filePath: string): Promise<TableSchema>;
+    parseFile(filePath: string): Promise<TableSchema | null>;
     parseDirectory(dirPath: string): Promise<TableSchema[]>;
 }
+/**
+ * Parse a single Sequelize Model file and extract TableSchema.
+ */
+declare function parseModelFile(filePath: string): TableSchema | null;
+/**
+ * Batch parse all Model files in a directory.
+ */
+declare function parseModuleModels(modelDir: string): TableSchema[];
 declare function createModelParser(): ModelParser;
 
 interface ControllerParser {
-    parseFile(filePath: string): Promise<RouteEntry[]>;
-    parseDirectory(dirPath: string): Promise<RouteEntry[]>;
+    parseFile(filePath: string): Promise<ApiEndpoint[]>;
+    parseDirectory(dirPath: string): Promise<ApiEndpoint[]>;
 }
+/**
+ * Parse a single Controller file and extract API endpoints.
+ */
+declare function parseControllerFile(filePath: string): ApiEndpoint[];
+/**
+ * Parse all Controller files in a directory.
+ */
+declare function parseControllerDirectory(dirPath: string): ApiEndpoint[];
+/**
+ * Infer related database table names from Service file imports.
+ */
+declare function inferRelatedTables(servicePaths: string[]): string[];
 declare function createControllerParser(): ControllerParser;
 
 interface AssociationParser {
     parseFile(filePath: string): Promise<ForeignKeyRelation[]>;
 }
+/**
+ * Parse an associations.ts file to extract all foreign key relations.
+ */
+declare function parseAssociationFile(filePath: string, classToTableMap?: Map<string, string>, moduleTablePrefix?: string): ForeignKeyRelation[];
+/**
+ * Build className → tableName map from Model files in a directory.
+ */
+declare function buildClassToTableMap(modelDir: string): Map<string, string>;
+declare function classNameToTableName(className: string): string;
 declare function createAssociationParser(): AssociationParser;
 
 interface TestCodeGenerator {
@@ -224,30 +295,268 @@ interface ERDiagramGenerator {
 }
 declare function createERDiagramGenerator(): ERDiagramGenerator;
 
+/**
+ * Infer API dependencies via path parameter matching.
+ * POST endpoints produce IDs; GET/PUT/DELETE endpoints consume them.
+ */
+declare function inferDependencies(endpoints: ApiEndpoint[]): ApiDependency[];
+/**
+ * Build a directed graph from endpoints and their dependencies.
+ */
+declare function buildGraph(endpoints: ApiEndpoint[], dependencies: ApiDependency[]): DirectedAcyclicGraph;
+/**
+ * Detect cycles in a directed graph using DFS coloring.
+ */
+declare function detectCycles(dag: DirectedAcyclicGraph): string[];
+/**
+ * Topological sort using Kahn's algorithm.
+ */
+declare function topologicalSort(dag: DirectedAcyclicGraph): string[];
 interface ApiChainAnalyzer {
-    analyze(endpoints: ApiEndpoint[]): {
-        dependencies: ApiDependency[];
-        topologicalOrder: ApiEndpoint[];
-    };
+    analyze(endpoints: ApiEndpoint[]): ApiChainAnalysisResult;
 }
+/**
+ * Analyze API endpoints: infer dependencies, build DAG, detect cycles, topological sort.
+ */
 declare function createApiChainAnalyzer(): ApiChainAnalyzer;
 
 interface ImpactReporter {
-    analyze(failedEndpoints: string[]): Promise<ImpactReport>;
+    analyze(failures: ChainFailureResult[], erDiagrams: Map<string, ERDiagramResult>, analysisResults: ApiChainAnalysisResult[]): ImpactReport;
 }
 declare function createImpactReporter(): ImpactReporter;
 
-declare function validateConfig(_config: Record<string, unknown>): ValidationError[];
+/**
+ * Validate an OpenCroc configuration object.
+ * Returns an array of ValidationErrors (empty = valid).
+ */
+declare function validateConfig(config: Record<string, unknown>): ValidationError[];
 
 interface SelfHealingLoop {
     run(testResultsDir: string): Promise<SelfHealingResult>;
 }
-interface SelfHealingResult {
-    iterations: number;
-    fixed: string[];
-    remaining: string[];
-    totalTokensUsed: number;
+/**
+ * Categorize a test failure by heuristic rules.
+ */
+declare function categorizeFailure(errorMessage: string): {
+    category: string;
+    confidence: number;
+};
+/**
+ * LLM-enhanced failure analysis with heuristic fallback.
+ */
+declare function analyzeFailureWithLLM(errorMessage: string, llm?: LlmProvider): Promise<{
+    rootCause: string;
+    category: string;
+    suggestedFix: string;
+    confidence: number;
+}>;
+/**
+ * Create a self-healing loop. Accepts an optional LLM provider for AI-enhanced analysis.
+ */
+declare function createSelfHealingLoop(config: SelfHealingConfig, llm?: LlmProvider): SelfHealingLoop;
+
+/**
+ * Create an OpenAI-compatible LLM provider.
+ * Works with OpenAI, Zhipu (GLM), and any OpenAI-compatible API.
+ */
+declare function createOpenAIProvider(config: LlmConfig): LlmProvider;
+
+/**
+ * Create an Ollama LLM provider for local model inference.
+ */
+declare function createOllamaProvider(config: LlmConfig): LlmProvider;
+
+/**
+ * Create an LLM provider from config.
+ * Resolves apiKey from config or OPENCROC_LLM_API_KEY env variable.
+ */
+declare function createLlmProvider(config: LlmConfig): LlmProvider;
+/**
+ * Token usage tracker — accumulates tokens across multiple LLM calls.
+ */
+interface TokenTracker {
+    track(text: string): void;
+    trackChat(messages: Array<{
+        role: string;
+        content: string;
+    }>, response: string): void;
+    total: number;
+    reset(): void;
+}
+declare function createTokenTracker(provider: LlmProvider): TokenTracker;
+/**
+ * System prompts for different LLM use cases in OpenCroc.
+ */
+declare const SYSTEM_PROMPTS: {
+    readonly failureAnalysis: "You are an expert test failure analyst for an E2E testing framework.\nGiven a test failure error message and its context, analyze the root cause and suggest a fix.\nRespond in JSON format: { \"rootCause\": string, \"category\": string, \"suggestedFix\": string, \"confidence\": number }\nCategories: backend-5xx, timeout, endpoint-not-found, data-constraint, network, frontend-render, test-script, unknown.";
+    readonly chainPlanning: "You are an API test chain planner.\nGiven a list of API endpoints and their dependencies, generate an optimal test execution order.\nConsider data dependencies, authentication requirements, and cleanup steps.\nRespond in JSON format: { \"chains\": [{ \"name\": string, \"steps\": [{ \"endpoint\": string, \"method\": string, \"description\": string }] }] }";
+};
+
+declare function createSequelizeAdapter(): BackendAdapter;
+
+declare function createTypeORMAdapter(): BackendAdapter;
+
+declare function createPrismaAdapter(): BackendAdapter;
+
+/**
+ * Create an adapter by name.
+ */
+declare function createAdapter(name: string): BackendAdapter;
+/**
+ * Auto-detect the ORM adapter from project structure.
+ *
+ * Detection order:
+ * 1. Prisma — if `prisma/schema.prisma` exists
+ * 2. TypeORM — if any .ts file has `@Entity` decorator
+ * 3. Sequelize — default fallback (`.init()` pattern)
+ */
+declare function detectAdapter(backendRoot: string): string;
+/**
+ * Resolve adapter: if a string name is given, create it; if already a BackendAdapter, use it.
+ * If 'auto', detect from project structure.
+ */
+declare function resolveAdapter(adapterOrName: string | BackendAdapter | undefined, backendRoot: string): BackendAdapter;
+
+/**
+ * Plugin lifecycle hooks.
+ *
+ * All hooks are optional. Async hooks are awaited in registration order.
+ */
+interface OpenCrocPlugin {
+    /** Unique plugin name (used for logging and deduplication) */
+    name: string;
+    /** Called once when the plugin is registered */
+    setup?(): void | Promise<void>;
+    /** Transform config before pipeline starts (return modified config) */
+    transformConfig?(config: OpenCrocConfig): OpenCrocConfig | Promise<OpenCrocConfig>;
+    /** Called before the full pipeline run */
+    beforePipeline?(config: OpenCrocConfig): void | Promise<void>;
+    /** Called after pipeline completes (receives result) */
+    afterPipeline?(result: PipelineRunResult, config: OpenCrocConfig): void | Promise<void>;
+    /** Called before each pipeline step */
+    beforeStep?(step: PipelineStep, config: OpenCrocConfig): void | Promise<void>;
+    /** Called after each pipeline step */
+    afterStep?(step: PipelineStep, result: PipelineRunResult, config: OpenCrocConfig): void | Promise<void>;
+    /** Called on pipeline error */
+    onError?(error: Error, step?: PipelineStep): void | Promise<void>;
+    /** Called once when the plugin is unregistered / teardown */
+    teardown?(): void | Promise<void>;
 }
-declare function createSelfHealingLoop(_config: SelfHealingConfig): SelfHealingLoop;
+/**
+ * Plugin registry interface.
+ */
+interface PluginRegistry {
+    /** Register a plugin. Duplicate names are rejected. */
+    register(plugin: OpenCrocPlugin): void;
+    /** Unregister a plugin by name. Calls teardown if defined. */
+    unregister(name: string): Promise<void>;
+    /** Get a registered plugin by name */
+    get(name: string): OpenCrocPlugin | undefined;
+    /** List all registered plugin names */
+    list(): string[];
+    /** Invoke a hook across all plugins in registration order */
+    invoke<K extends keyof OpenCrocPlugin>(hook: K, ...args: Parameters<NonNullable<OpenCrocPlugin[K]> extends (...a: infer P) => unknown ? (...a: P) => unknown : never>): Promise<void>;
+    /** Invoke transformConfig — applies transforms sequentially and returns final config */
+    applyConfigTransforms(config: OpenCrocConfig): Promise<OpenCrocConfig>;
+}
+
+/**
+ * Create a plugin registry.
+ *
+ * @example
+ * ```ts
+ * const registry = createPluginRegistry();
+ * registry.register({ name: 'my-plugin', beforePipeline() { console.log('go!'); } });
+ * await registry.invoke('beforePipeline', config);
+ * ```
+ */
+declare function createPluginRegistry(): PluginRegistry;
+/**
+ * Helper to define a plugin with type safety.
+ */
+declare function definePlugin(plugin: OpenCrocPlugin): OpenCrocPlugin;
+
+/**
+ * CI template generators for popular CI/CD platforms.
+ *
+ * Usage:
+ *   npx opencroc ci --platform=github
+ *   npx opencroc ci --platform=gitlab
+ */
+interface CiTemplateOptions {
+    /** Node.js version(s). Default: ['20.x'] */
+    nodeVersions?: string[];
+    /** Install command. Default: 'npm ci' */
+    installCommand?: string;
+    /** Whether to run self-healing. Default: false */
+    selfHeal?: boolean;
+    /** Custom opencroc generate args */
+    generateArgs?: string;
+    /** Custom opencroc test args */
+    testArgs?: string;
+}
+declare function generateGitHubActionsTemplate(opts?: CiTemplateOptions): string;
+declare function generateGitLabCITemplate(opts?: CiTemplateOptions): string;
+/**
+ * Get available CI platform names.
+ */
+declare function listCiPlatforms(): string[];
+/**
+ * Generate a CI template for the given platform.
+ */
+declare function generateCiTemplate(platform: string, opts?: CiTemplateOptions): string;
+
+interface ReportOutput {
+    format: 'html' | 'json' | 'markdown';
+    content: string;
+    filename: string;
+}
+declare function generateJsonReport(result: PipelineRunResult): ReportOutput;
+declare function generateMarkdownReport(result: PipelineRunResult): ReportOutput;
+declare function generateHtmlReport(result: PipelineRunResult): ReportOutput;
+/**
+ * Generate reports in the specified formats.
+ */
+declare function generateReports(result: PipelineRunResult, formats?: ('html' | 'json' | 'markdown')[]): ReportOutput[];
+
+/**
+ * VSCode extension scaffold for OpenCroc.
+ *
+ * This module provides the extension activation logic, command definitions,
+ * and tree view data provider for the OpenCroc sidebar panel.
+ *
+ * To build:
+ *   1. Copy `vscode-extension/` from the opencroc repo
+ *   2. Run `npm install && npm run compile`
+ *   3. Press F5 in VS Code to launch the Extension Development Host
+ */
+interface ExtensionCommand {
+    command: string;
+    title: string;
+    category: string;
+}
+interface TreeItem {
+    label: string;
+    description?: string;
+    tooltip?: string;
+    iconId?: string;
+    children?: TreeItem[];
+    command?: string;
+}
+declare const COMMANDS: ExtensionCommand[];
+declare function buildModuleTree(modules: string[]): TreeItem[];
+declare function buildStatusTree(stats: {
+    modules: number;
+    tables: number;
+    relations: number;
+    generatedFiles: number;
+    errors: number;
+}): TreeItem[];
+declare function generateExtensionManifest(): Record<string, unknown>;
+/**
+ * Generate the extension's entry point (activation function).
+ * Returns TypeScript source code for `src/extension.ts`.
+ */
+declare function generateExtensionEntrypoint(): string;
 
-export { type ApiDependency, type ApiEndpoint, type BackendAdapter, type ChainFailureResult, type ChainPlanResult, type ERDiagramResult, type FieldSchema, type ForeignKeyRelation, type GeneratedTestFile, type ImpactReport, type LlmProvider, type ModuleDefinition, type OpenCrocConfig, type PipelineRunResult, type ResolvedConfig, type RouteEntry, type TableSchema, type TestChain, type TestStep, createApiChainAnalyzer, createAssociationParser, createControllerParser, createERDiagramGenerator, createImpactReporter, createMockDataGenerator, createModelParser, createPipeline, createSelfHealingLoop, createTestCodeGenerator, defineConfig, validateConfig };
+export { type ApiChainAnalysisResult, type ApiDependency, type ApiEndpoint, type BackendAdapter, type ChainFailureResult, type ChainPlanResult, type DirectedAcyclicGraph, type ERDiagramResult, type FieldSchema, type FixOutcome, type ForeignKeyRelation, type GeneratedTestFile, type ImpactReport, type IndexSchema, type LlmProvider, type ModuleDefinition, type OpenCrocConfig, type OpenCrocPlugin, type PipelineRunResult, type PluginRegistry, type ReportOutput, type ResolvedConfig, type RouteEntry, SYSTEM_PROMPTS, type SelfHealingResult, type TableSchema, type TestChain, type TestStep, COMMANDS as VSCODE_COMMANDS, type ValidationError, analyzeFailureWithLLM, buildClassToTableMap, buildGraph, buildModuleTree, buildStatusTree, categorizeFailure, classNameToTableName, createAdapter, createApiChainAnalyzer, createAssociationParser, createControllerParser, createERDiagramGenerator, createImpactReporter, createLlmProvider, createMockDataGenerator, createModelParser, createOllamaProvider, createOpenAIProvider, createPipeline, createPluginRegistry, createPrismaAdapter, createSelfHealingLoop, createSequelizeAdapter, createTestCodeGenerator, createTokenTracker, createTypeORMAdapter, defineConfig, definePlugin, detectAdapter, detectCycles, generateCiTemplate, generateExtensionEntrypoint, generateExtensionManifest, generateGitHubActionsTemplate, generateGitLabCITemplate, generateHtmlReport, generateJsonReport, generateMarkdownReport, generateReports, inferDependencies, inferRelatedTables, listCiPlatforms, parseAssociationFile, parseControllerDirectory, parseControllerFile, parseModelFile, parseModuleModels, resolveAdapter, topologicalSort, validateConfig };