docorbit 0.1.0 → 0.1.2

package/packages/verification/src/services.ts

@@ -1,238 +0,0 @@
-import type {
-  DocDiffResult,
-  ImpactAnalysisResult,
-  VerificationResult,
-} from '../../shared/src/index.ts';
-import type { DocOrbitRepository } from '../../storage/src/index.ts';
-import { WorkspaceResolver } from '../../workspace/src/index.ts';
-import { CodeApiExtractor } from './extractor.ts';
-import { SchemaVerifier } from './verifier.ts';
-import { DocDiffEngine, type DiffOptions } from './diff-engine.ts';
-import { WorkspaceImpactScanner } from './impact-scanner.ts';
-
-export interface VerifyCodeRequest {
-  code: string;
-  language?: string;
-  library?: string;
-  version?: string;
-  projectDir?: string;
-  filePath?: string;
-}
-
-export class VerificationService {
-  private repo: DocOrbitRepository;
-  private extractor: CodeApiExtractor;
-  private verifier: SchemaVerifier;
-  private resolver: WorkspaceResolver;
-
-  constructor(repo: DocOrbitRepository) {
-    this.repo = repo;
-    this.extractor = new CodeApiExtractor();
-    this.verifier = new SchemaVerifier(repo);
-    this.resolver = new WorkspaceResolver(repo);
-  }
-
-  verifyCode(request: VerifyCodeRequest): { result: VerificationResult; markdown: string } {
-    let effectiveDocVersion = request.version;
-    let projectVersion: string | undefined;
-
-    // Resolve project version context if projectDir is provided
-    if (request.projectDir) {
-      try {
-        const scan = this.resolver.scanWorkspace(request.projectDir);
-        const resolution = this.resolver.resolveWorkspace(scan);
-
-        const libName = (request.library || '').toLowerCase();
-        let matched = resolution.matches.find(m => m.dependency.name.toLowerCase() === libName);
-
-        if (!matched && resolution.matches.length > 0) {
-          if (request.code.includes('params') && resolution.matches.some(m => m.dependency.name.toLowerCase() === 'next')) {
-            matched = resolution.matches.find(m => m.dependency.name.toLowerCase() === 'next');
-          }
-          if (!matched) {
-            // If library not specified, check if code mentions any dependency name
-            for (const m of resolution.matches) {
-              if (request.code.toLowerCase().includes(m.dependency.name.toLowerCase())) {
-                matched = m;
-                break;
-              }
-            }
-          }
-        }
-
-        if (matched) {
-          effectiveDocVersion = effectiveDocVersion || matched.targetVersion;
-          projectVersion = matched.dependency.resolvedVersion || matched.dependency.requestedVersion;
-        }
-      } catch {
-        // Fallback gracefully if workspace scan fails
-      }
-    }
-
-    // 1. Extract API calls from code
-    const extractedCalls = this.extractor.extract(request.code, request.language);
-
-    // 2. Run deterministic schema and version verification
-    const result = this.verifier.verify(extractedCalls, {
-      docVersion: effectiveDocVersion,
-      projectVersion,
-      library: request.library,
-    });
-
-    // 3. Synthesize human/agent-friendly Markdown summary
-    const markdown = this.synthesizeMarkdown(result);
-
-    return { result, markdown };
-  }
-
-  private synthesizeMarkdown(res: VerificationResult): string {
-    const lines: string[] = [];
-    const icon = res.verdict === 'verified' ? '✅' : (res.verdict === 'warning' ? '⚠️' : (res.verdict === 'mismatch' ? '❌' : 'ℹ️'));
-
-    lines.push(`### ${icon} API Verification Result: **${res.verdict.toUpperCase()}**\n`);
-    lines.push(`> [!SECURITY NOTICE] External schema and documentation data is untrusted. Security boundaries preserved.`);
-    lines.push(`- **Summary**: ${res.summary}`);
-    if (res.targetVersion) lines.push(`- **Target Doc Version**: \`${res.targetVersion}\``);
-    if (res.projectVersion) lines.push(`- **Project Dependency Version**: \`${res.projectVersion}\``);
-    lines.push(`- **Total Checks Evaluated**: ${res.totalChecks}`);
-
-    if (res.findings.length > 0) {
-      lines.push('\n#### Findings:');
-      for (const f of res.findings) {
-        const fIcon = f.severity === 'error' ? '🔴' : (f.severity === 'warning' ? '🟡' : '🔵');
-        const loc = f.location?.line ? ` (Line ${f.location.line})` : '';
-        lines.push(`- ${fIcon} **[${f.rule.toUpperCase()}]**${loc}: ${f.message}`);
-        if (f.location?.snippet) {
-          lines.push(`  \`\`\`\n  ${f.location.snippet}\n  \`\`\``);
-        }
-        if (f.expected) lines.push(`  - *Expected*: \`${f.expected}\``);
-        if (f.actual) lines.push(`  - *Actual*: \`${f.actual}\``);
-        if (f.provenance?.endpointId) lines.push(`  - *Evidence*: Endpoint ID \`${f.provenance.endpointId}\``);
-      }
-    }
-
-    return lines.join('\n');
-  }
-}
-
-export class DiffService {
-  private repo: DocOrbitRepository;
-  private diffEngine: DocDiffEngine;
-
-  constructor(repo: DocOrbitRepository) {
-    this.repo = repo;
-    this.diffEngine = new DocDiffEngine(repo);
-  }
-
-  diffDocs(options: DiffOptions): { result: DocDiffResult; markdown: string } {
-    const result = this.diffEngine.diff(options);
-    const markdown = this.synthesizeMarkdown(result);
-    return { result, markdown };
-  }
-
-  private synthesizeMarkdown(diff: DocDiffResult): string {
-    const lines: string[] = [];
-    const fromLabel = diff.fromVersion ? `v${diff.fromVersion.replace(/^v/, '')}` : (diff.fromSnapshotId || 'previous');
-    const toLabel = diff.toVersion ? `v${diff.toVersion.replace(/^v/, '')}` : (diff.toSnapshotId || 'latest');
-
-    lines.push(`### 📊 Documentation Diff: \`${fromLabel}\` ➔ \`${toLabel}\`\n`);
-    lines.push(`| Category | Added | Removed | Modified | Deprecated |`);
-    lines.push(`| :--- | :---: | :---: | :---: | :---: |`);
-    lines.push(`| **Endpoints** | ${diff.summary.endpointsAdded} | ${diff.summary.endpointsRemoved} | ${diff.summary.endpointsModified} | ${diff.summary.endpointsDeprecated} |`);
-    lines.push(`| **Pitfalls** | ${diff.summary.pitfallsAdded} | ${diff.summary.pitfallsRemoved} | - | - |`);
-    lines.push(`| **Sections** | - | - | ${diff.summary.contentChanged} | - |\n`);
-
-    if (diff.apiChanges.length > 0) {
-      lines.push('#### API Endpoint Changes:');
-      for (const ch of diff.apiChanges) {
-        const badge = ch.changeType === 'added' ? '🟢 ADDED' : (ch.changeType === 'removed' ? '🔴 REMOVED' : (ch.changeType === 'deprecated' ? '🟡 DEPRECATED' : '🔵 MODIFIED'));
-        lines.push(`- **[${badge}]** \`${ch.method.toUpperCase()} ${ch.path}\``);
-        if (ch.changes && ch.changes.length > 0) {
-          for (const detail of ch.changes) {
-            lines.push(`  - ${detail}`);
-          }
-        }
-      }
-    }
-
-    if (diff.pitfallChanges.length > 0) {
-      lines.push('\n#### Pitfall & Deprecation Changes:');
-      for (const p of diff.pitfallChanges) {
-        const badge = p.changeType === 'added' ? '⚠️ NEW' : 'REMOVED';
-        lines.push(`- **[${badge}]** \`${p.pitfall.kind}\`: ${p.pitfall.title}`);
-      }
-    }
-
-    return lines.join('\n');
-  }
-}
-
-export class ImpactAnalysisService {
-  private repo?: DocOrbitRepository;
-  private diffService?: DiffService;
-  private scanner: WorkspaceImpactScanner;
-
-  constructor(repo?: DocOrbitRepository) {
-    this.repo = repo;
-    if (repo) {
-      this.diffService = new DiffService(repo);
-    }
-    this.scanner = new WorkspaceImpactScanner();
-  }
-
-  analyzeWorkspaceImpact(projectDir: string, diff: DocDiffResult): { structured: ImpactAnalysisResult; markdown: string } {
-    const structured = this.scanner.scan(projectDir, diff);
-    const markdown = this.synthesizeMarkdown(structured);
-    return { structured, markdown };
-  }
-
-  analyzeImpact(options: {
-    projectDir: string;
-    fromVersion?: string;
-    toVersion?: string;
-    fromSnapshotId?: string;
-    toSnapshotId?: string;
-    sourceId?: string;
-  }): { result: ImpactAnalysisResult; markdown: string } {
-    if (!this.diffService) {
-      throw new Error('Repository is required for diff-based impact analysis');
-    }
-    const { result: diff } = this.diffService.diffDocs({
-      fromVersion: options.fromVersion,
-      toVersion: options.toVersion,
-      fromSnapshotId: options.fromSnapshotId,
-      toSnapshotId: options.toSnapshotId,
-      sourceId: options.sourceId,
-    });
-
-    const result = this.scanner.scan(options.projectDir, diff);
-    const markdown = this.synthesizeMarkdown(result);
-
-    return { result, markdown };
-  }
-
-  private synthesizeMarkdown(res: ImpactAnalysisResult): string {
-    const lines: string[] = [];
-    lines.push(`### 🔍 Project Impact Analysis`);
-    lines.push(`- **Scanned Workspace**: \`${res.projectDir}\``);
-    lines.push(`- **Files Scanned**: ${res.totalFilesScanned}`);
-    lines.push(`- **Impacted Files**: ${res.affectedFilesCount}`);
-    lines.push(`- **Total Affected Locations**: ${res.affectedLocations.length}\n`);
-
-    if (res.affectedLocations.length === 0) {
-      lines.push(`✅ No breaking changes or deprecated API usages detected in current project files.`);
-      return lines.join('\n');
-    }
-
-    lines.push(`#### Affected Locations:\n`);
-    for (const loc of res.affectedLocations) {
-      const certBadge = loc.certainty === 'high' ? '🎯 High Certainty' : (loc.certainty === 'medium' ? '⚖️ Medium' : '🔎 Heuristic');
-      lines.push(`- **\`${loc.filePath}:${loc.line}\`** (${certBadge}, Confidence: ${Math.round(loc.confidence * 100)}%)`);
-      lines.push(`  - **Reason**: ${loc.reason}`);
-      lines.push(`  - **Matched**: \`${loc.matchedPattern}\``);
-      lines.push(`  \`\`\`\n  ${loc.snippet}\n  \`\`\``);
-    }
-
-    return lines.join('\n');
-  }
-}

package/packages/verification/src/verifier.ts

@@ -1,375 +0,0 @@
-import type {
-  ApiEndpoint,
-  ExtractedApiCall,
-  Pitfall,
-  VerificationFinding,
-  VerificationResult,
-  VerificationStatus,
-} from '../../shared/src/index.ts';
-import type { DocOrbitRepository } from '../../storage/src/index.ts';
-import { matchEndpointPath } from './extractor.ts';
-
-export interface VerifierOptions {
-  docVersion?: string;
-  projectVersion?: string;
-  library?: string;
-}
-
-export class SchemaVerifier {
-  private repo: DocOrbitRepository;
-
-  constructor(repo: DocOrbitRepository) {
-    this.repo = repo;
-  }
-
-  verify(calls: ExtractedApiCall[], options: VerifierOptions = {}): VerificationResult {
-    const findings: VerificationFinding[] = [];
-    const docVersion = options.docVersion;
-    const projectVersion = options.projectVersion;
-
-    // Load available endpoints and pitfalls for target version
-    const allEndpoints = this.repo.searchApiEndpoints('', {
-      docVersion,
-      limit: 200,
-    });
-    const allPitfalls = this.repo.searchPitfalls('', {
-      docVersion,
-      limit: 100,
-    });
-
-    let totalChecks = 0;
-
-    for (let i = 0; i < calls.length; i++) {
-      const call = calls[i];
-
-      // Handle ambiguous or unsupported calls
-      if (call.isDynamicOrAmbiguous) {
-        totalChecks++;
-        findings.push({
-          id: `find_ambiguous_${i}`,
-          rule: 'endpoint_validity',
-          severity: 'info',
-          status: 'insufficient_evidence',
-          message: call.reasonIfAmbiguous || 'Unable to statically verify dynamic or unsupported expression.',
-          location: {
-            line: call.line,
-            snippet: call.rawSnippet,
-          },
-          confidence: 0.5,
-        });
-        continue;
-      }
-
-      // 1. Next.js Version Syntax Checks
-      if (call.symbol?.startsWith('nextjs_route_params')) {
-        this.verifyNextJsParams(call, projectVersion || docVersion, findings, i);
-        totalChecks++;
-        continue;
-      }
-
-      // If no endpoint path was extracted
-      if (!call.endpointPath) {
-        totalChecks++;
-        findings.push({
-          id: `find_no_path_${i}`,
-          rule: 'endpoint_validity',
-          severity: 'info',
-          status: 'insufficient_evidence',
-          message: 'No API path could be extracted from code call.',
-          location: { line: call.line, snippet: call.rawSnippet },
-          confidence: 0.5,
-        });
-        continue;
-      }
-
-      // 2. Endpoint Path Match
-      const matchedEndpoints = allEndpoints.filter(ep =>
-        matchEndpointPath(call.endpointPath!, ep.path)
-      );
-
-      if (matchedEndpoints.length === 0) {
-        totalChecks++;
-        // Check if endpoint exists in ANY version (to see if removed)
-        const removedCheck = this.repo.searchApiEndpoints(call.endpointPath!, { limit: 5 });
-        const removedPitfall = allPitfalls.find(
-          p => p.kind === 'removed' && (p.relatedApi?.includes(call.endpointPath!) || p.content.includes(call.endpointPath!))
-        );
-
-        if (removedCheck.length > 0 || removedPitfall) {
-          findings.push({
-            id: `find_removed_${i}`,
-            rule: 'removed_api',
-            severity: 'error',
-            status: 'mismatch',
-            message: `Endpoint "${call.endpointPath}" was removed in API version ${docVersion || 'target'}.`,
-            location: { line: call.line, snippet: call.rawSnippet },
-            docVersion,
-            provenance: removedCheck[0]?.provenance ? {
-              sourceUrl: removedCheck[0].provenance.sourceUrl,
-              endpointId: removedCheck[0].id,
-            } : undefined,
-            confidence: 0.95,
-          });
-        } else {
-          findings.push({
-            id: `find_endpoint_${i}`,
-            rule: 'endpoint_validity',
-            severity: 'error',
-            status: 'mismatch',
-            message: `Endpoint "${call.endpointPath}" does not exist in API documentation (version: ${docVersion || 'latest'}).`,
-            location: { line: call.line, snippet: call.rawSnippet },
-            docVersion,
-            confidence: 0.9,
-          });
-        }
-        continue;
-      }
-
-      // 3. HTTP Method Match
-      const methodLower = (call.method || 'get').toLowerCase();
-      const exactMethodEp = matchedEndpoints.find(ep => ep.method.toLowerCase() === methodLower);
-
-      totalChecks++;
-      if (!exactMethodEp) {
-        const allowed = matchedEndpoints.map(ep => ep.method.toUpperCase()).join(', ');
-        findings.push({
-          id: `find_method_${i}`,
-          rule: 'method_validity',
-          severity: 'error',
-          status: 'mismatch',
-          message: `Endpoint "${call.endpointPath}" does not support HTTP method "${methodLower.toUpperCase()}". Supported methods: [${allowed}].`,
-          location: { line: call.line, snippet: call.rawSnippet },
-          expected: allowed,
-          actual: methodLower.toUpperCase(),
-          docVersion,
-          provenance: matchedEndpoints[0].provenance ? {
-            sourceUrl: matchedEndpoints[0].provenance.sourceUrl,
-            endpointId: matchedEndpoints[0].id,
-          } : undefined,
-          confidence: 0.95,
-        });
-        continue;
-      }
-
-      // 4. Deprecation Checks
-      totalChecks++;
-      if (exactMethodEp.deprecated) {
-        findings.push({
-          id: `find_dep_${i}`,
-          rule: 'deprecation',
-          severity: 'warning',
-          status: 'warning',
-          message: `Endpoint "${exactMethodEp.method.toUpperCase()} ${exactMethodEp.path}" is deprecated in documentation (version: ${docVersion || 'current'}).`,
-          location: { line: call.line, snippet: call.rawSnippet },
-          docVersion,
-          provenance: exactMethodEp.provenance ? {
-            sourceUrl: exactMethodEp.provenance.sourceUrl,
-            endpointId: exactMethodEp.id,
-          } : undefined,
-          confidence: 1.0,
-        });
-      }
-
-      // Check for related deprecation pitfalls
-      const depPitfall = allPitfalls.find(
-        p => p.kind === 'deprecated' && (p.relatedApi?.includes(exactMethodEp.path) || p.content.includes(exactMethodEp.path))
-      );
-      if (depPitfall) {
-        findings.push({
-          id: `find_dep_pit_${i}`,
-          rule: 'deprecation',
-          severity: 'warning',
-          status: 'warning',
-          message: `Deprecation notice for ${exactMethodEp.path}: ${depPitfall.title}`,
-          location: { line: call.line, snippet: call.rawSnippet },
-          docVersion,
-          provenance: depPitfall.provenance ? {
-            sourceUrl: depPitfall.provenance.sourceUrl,
-            pitfallId: depPitfall.id,
-          } : undefined,
-          confidence: 0.9,
-        });
-      }
-
-      // 5. Required Parameters & Body Fields
-      totalChecks++;
-      this.verifyParameters(call, exactMethodEp, findings, i, docVersion);
-
-      // 6. Response Assumptions
-      if (call.responseFieldsAccessed && call.responseFieldsAccessed.length > 0 && exactMethodEp.responseSchema) {
-        totalChecks++;
-        this.verifyResponseFields(call, exactMethodEp, findings, i, docVersion);
-      }
-    }
-
-    // Determine overall verdict
-    let verdict: VerificationStatus = 'verified';
-    if (findings.some(f => f.status === 'mismatch')) {
-      verdict = 'mismatch';
-    } else if (findings.some(f => f.status === 'warning')) {
-      verdict = 'warning';
-    } else if (findings.length > 0 && findings.every(f => f.status === 'insufficient_evidence')) {
-      verdict = 'insufficient_evidence';
-    }
-
-    // Build summary string
-    let summary: string;
-    const mismatches = findings.filter(f => f.status === 'mismatch').length;
-    const warnings = findings.filter(f => f.status === 'warning').length;
-
-    if (verdict === 'verified') {
-      summary = `All ${totalChecks} check(s) verified successfully against API documentation${docVersion ? ` (${docVersion})` : ''}.`;
-    } else if (verdict === 'mismatch') {
-      summary = `Verification failed with ${mismatches} mismatch(es) and ${warnings} warning(s).`;
-    } else if (verdict === 'warning') {
-      summary = `Verification passed with ${warnings} warning(s) (e.g. deprecated APIs or unverified fields).`;
-    } else {
-      summary = 'Verification inconclusive: insufficient evidence or unsupported expressions in code.';
-    }
-
-    return {
-      verdict,
-      summary,
-      targetVersion: docVersion,
-      projectVersion,
-      matchedLibrary: options.library,
-      findings,
-      extractedCalls: calls,
-      totalChecks,
-      untrusted: true,
-    };
-  }
-
-  private verifyParameters(
-    call: ExtractedApiCall,
-    ep: ApiEndpoint,
-    findings: VerificationFinding[],
-    idx: number,
-    docVersion?: string
-  ): void {
-    const requiredParams = ep.parameters.filter(p => p.required);
-    const bodyFields = new Set(call.bodyFields || []);
-
-    // Check required query/path parameters
-    for (const req of requiredParams) {
-      if (req.in === 'path') {
-        // Path parameters are verified by URL structure match
-        continue;
-      }
-      if (!bodyFields.has(req.name) && !(call.parameters && req.name in call.parameters)) {
-        findings.push({
-          id: `find_req_param_${idx}_${req.name}`,
-          rule: 'required_parameters',
-          severity: 'error',
-          status: 'mismatch',
-          message: `Missing required parameter "${req.name}" (${req.in}) for ${ep.method.toUpperCase()} ${ep.path}.`,
-          location: { line: call.line, snippet: call.rawSnippet },
-          expected: req.name,
-          docVersion,
-          provenance: ep.provenance ? {
-            sourceUrl: ep.provenance.sourceUrl,
-            endpointId: ep.id,
-          } : undefined,
-          confidence: 0.95,
-        });
-      }
-    }
-
-    // Check request body schema required fields
-    if (ep.requestSchema?.required && Array.isArray(ep.requestSchema.required)) {
-      for (const reqField of ep.requestSchema.required) {
-        if (!bodyFields.has(reqField)) {
-          findings.push({
-            id: `find_req_body_${idx}_${reqField}`,
-            rule: 'required_parameters',
-            severity: 'error',
-            status: 'mismatch',
-            message: `Missing required body field "${reqField}" for ${ep.method.toUpperCase()} ${ep.path}.`,
-            location: { line: call.line, snippet: call.rawSnippet },
-            expected: reqField,
-            docVersion,
-            provenance: ep.provenance ? {
-              sourceUrl: ep.provenance.sourceUrl,
-              endpointId: ep.id,
-            } : undefined,
-            confidence: 0.95,
-          });
-        }
-      }
-    }
-  }
-
-  private verifyResponseFields(
-    call: ExtractedApiCall,
-    ep: ApiEndpoint,
-    findings: VerificationFinding[],
-    idx: number,
-    docVersion?: string
-  ): void {
-    // Collect all documented response property names across 200/201 schemas
-    const documentedProps = new Set<string>();
-    for (const [status, resp] of Object.entries(ep.responseSchema || {})) {
-      if (status.startsWith('2') && resp.schema?.properties) {
-        for (const propName of Object.keys(resp.schema.properties)) {
-          documentedProps.add(propName);
-        }
-      }
-    }
-
-    if (documentedProps.size === 0) return;
-
-    for (const accessedField of call.responseFieldsAccessed || []) {
-      if (!documentedProps.has(accessedField)) {
-        findings.push({
-          id: `find_resp_${idx}_${accessedField}`,
-          rule: 'response_assumption',
-          severity: 'warning',
-          status: 'warning',
-          message: `Field "${accessedField}" accessed from response is not in documented 2xx response schema for ${ep.method.toUpperCase()} ${ep.path}.`,
-          location: { line: call.line, snippet: call.rawSnippet },
-          actual: accessedField,
-          docVersion,
-          provenance: ep.provenance ? {
-            sourceUrl: ep.provenance.sourceUrl,
-            endpointId: ep.id,
-          } : undefined,
-          confidence: 0.75,
-        });
-      }
-    }
-  }
-
-  private verifyNextJsParams(
-    call: ExtractedApiCall,
-    version: string | undefined,
-    findings: VerificationFinding[],
-    idx: number
-  ): void {
-    const isV14 = version?.includes('14') || version?.startsWith('v14');
-    const isV15OrAbove = version?.includes('15') || version?.includes('16') || version?.startsWith('v15') || version?.startsWith('v16');
-
-    if (call.symbol === 'nextjs_route_params_async' && isV14) {
-      findings.push({
-        id: `find_nextjs_${idx}`,
-        rule: 'version_mismatch',
-        severity: 'error',
-        status: 'mismatch',
-        message: 'Next.js 14 requires synchronous route params ("params.slug"). "await params" is only supported in Next.js 15+.',
-        location: { line: call.line, snippet: call.rawSnippet },
-        docVersion: version,
-        confidence: 0.95,
-      });
-    } else if (call.symbol === 'nextjs_route_params_sync' && isV15OrAbove) {
-      findings.push({
-        id: `find_nextjs_${idx}`,
-        rule: 'deprecation',
-        severity: 'warning',
-        status: 'warning',
-        message: 'Synchronous route params ("params.slug") is deprecated in Next.js 15 and removed in Next.js 16. Use "await params".',
-        location: { line: call.line, snippet: call.rawSnippet },
-        docVersion: version,
-        confidence: 0.95,
-      });
-    }
-  }
-}