docorbit 0.1.0

package/packages/verification/src/impact-scanner.ts

@@ -0,0 +1,203 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type {
+  AffectedFileLocation,
+  DocDiffResult,
+  ImpactAnalysisResult,
+} from '../../shared/src/index.ts';
+
+const SOURCE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.py', '.go', '.json',
+]);
+
+const IGNORED_DIRS = new Set([
+  'node_modules', '.git', '.docorbit', 'dist', 'build', '.next', 'coverage',
+]);
+
+export class WorkspaceImpactScanner {
+  /**
+   * Scans a workspace project directory and identifies files affected by documentation diffs.
+   */
+  scan(projectDir: string, diff: DocDiffResult): ImpactAnalysisResult {
+    const files = this.collectFiles(projectDir);
+    const affectedLocations: AffectedFileLocation[] = [];
+
+    for (const filePath of files) {
+      this.analyzeFile(filePath, projectDir, diff, affectedLocations);
+    }
+
+    const uniqueFiles = new Set(affectedLocations.map(loc => loc.filePath));
+
+    let summary: string;
+    if (affectedLocations.length === 0) {
+      summary = `No project files affected across ${files.length} scanned file(s).`;
+    } else {
+      summary = `Found ${affectedLocations.length} affected location(s) across ${uniqueFiles.size} file(s).`;
+    }
+
+    return {
+      projectDir,
+      fromVersion: diff.fromVersion,
+      toVersion: diff.toVersion,
+      totalFilesScanned: files.length,
+      affectedFilesCount: uniqueFiles.size,
+      affectedLocations,
+      summary,
+    };
+  }
+
+  private collectFiles(dir: string): string[] {
+    const results: string[] = [];
+    if (!fs.existsSync(dir)) return results;
+
+    const traverse = (currentDir: string) => {
+      let entries: fs.Dirent[];
+      try {
+        entries = fs.readdirSync(currentDir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+
+      for (const entry of entries) {
+        if (IGNORED_DIRS.has(entry.name)) continue;
+
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+          traverse(fullPath);
+        } else if (entry.isFile()) {
+          const ext = path.extname(entry.name).toLowerCase();
+          if (SOURCE_EXTENSIONS.has(ext)) {
+            results.push(fullPath);
+          }
+        }
+      }
+    };
+
+    traverse(dir);
+    return results;
+  }
+
+  private analyzeFile(
+    fullPath: string,
+    projectDir: string,
+    diff: DocDiffResult,
+    out: AffectedFileLocation[]
+  ): void {
+    let content: string;
+    try {
+      content = fs.readFileSync(fullPath, 'utf8');
+    } catch {
+      return;
+    }
+
+    const relPath = path.relative(projectDir, fullPath);
+    const lines = content.split('\n');
+
+    // Quick pre-filter: check imports
+    const hasStripe = content.includes('stripe');
+    const hasNext = content.includes('next');
+
+    // 1. Scan for API endpoint removals, deprecations, and parameter modifications
+    for (const apiChange of diff.apiChanges) {
+      const epPath = apiChange.path;
+      const cleanPath = epPath.replace(/^\//, '');
+
+      for (let i = 0; i < lines.length; i++) {
+        const lineText = lines[i];
+
+        // Check if line contains endpoint path
+        if (lineText.includes(epPath) || lineText.includes(`'${cleanPath}'`) || lineText.includes(`"${cleanPath}"`)) {
+          if (apiChange.changeType === 'removed') {
+            out.push({
+              filePath: relPath,
+              line: i + 1,
+              snippet: lineText.trim(),
+              reason: `Endpoint "${apiChange.method.toUpperCase()} ${epPath}" was removed in API documentation.`,
+              matchedPattern: epPath,
+              changeCategory: 'removed_api',
+              certainty: 'high',
+              confidence: 0.95,
+              relatedChange: { endpoint: epPath },
+            });
+          } else if (apiChange.changeType === 'deprecated') {
+            out.push({
+              filePath: relPath,
+              line: i + 1,
+              snippet: lineText.trim(),
+              reason: `Endpoint "${apiChange.method.toUpperCase()} ${epPath}" is deprecated in API documentation.`,
+              matchedPattern: epPath,
+              changeCategory: 'deprecated_api',
+              certainty: 'high',
+              confidence: 0.9,
+              relatedChange: { endpoint: epPath },
+            });
+          } else if (apiChange.changeType === 'modified') {
+            out.push({
+              filePath: relPath,
+              line: i + 1,
+              snippet: lineText.trim(),
+              reason: `Endpoint parameters/schemas changed: ${(apiChange.changes || []).join('; ')}`,
+              matchedPattern: epPath,
+              changeCategory: 'modified_parameters',
+              certainty: 'high',
+              confidence: 0.85,
+              relatedChange: { endpoint: epPath },
+            });
+          }
+        }
+      }
+    }
+
+    // 2. Scan for breaking pitfalls and deprecations
+    for (const pitChange of diff.pitfallChanges) {
+      const pit = pitChange.pitfall;
+      if (pitChange.changeType !== 'added') continue;
+
+      const matchedLinesForThisPitfall = new Set<number>();
+
+      // Next.js Route Params sync deprecation / removal
+      if (pit.content.includes('params.slug') || pit.title.includes('route params') || pit.title.includes('Route Parameters')) {
+        for (let i = 0; i < lines.length; i++) {
+          const lineText = lines[i];
+          if (lineText.includes('params.') && !lineText.includes('await params') && hasNext) {
+            matchedLinesForThisPitfall.add(i + 1);
+            out.push({
+              filePath: relPath,
+              line: i + 1,
+              snippet: lineText.trim(),
+              reason: `Synchronous route parameter access detected. Documentation deprecation notice: ${pit.title}`,
+              matchedPattern: 'params.',
+              changeCategory: 'breaking_pitfall',
+              certainty: hasNext ? 'medium' : 'heuristic',
+              confidence: hasNext ? 0.85 : 0.6,
+              relatedChange: { pitfallTitle: pit.title },
+            });
+          }
+        }
+      }
+
+      // Check symbol references
+      if (pit.relatedSymbol) {
+        for (let i = 0; i < lines.length; i++) {
+          if (matchedLinesForThisPitfall.has(i + 1)) continue;
+          const lineText = lines[i];
+          if (lineText.includes(pit.relatedSymbol)) {
+            matchedLinesForThisPitfall.add(i + 1);
+            out.push({
+              filePath: relPath,
+              line: i + 1,
+              snippet: lineText.trim(),
+              reason: `Symbol "${pit.relatedSymbol}" referenced in file has documented pitfall: ${pit.title}`,
+              matchedPattern: pit.relatedSymbol,
+              changeCategory: 'breaking_pitfall',
+              certainty: (hasStripe || hasNext) ? 'medium' : 'heuristic',
+              confidence: (hasStripe || hasNext) ? 0.8 : 0.5,
+              relatedChange: { symbol: pit.relatedSymbol, pitfallTitle: pit.title },
+            });
+          }
+        }
+      }
+    }
+  }
+}

package/packages/verification/src/index.ts

@@ -0,0 +1,5 @@
+export * from './extractor.ts';
+export * from './verifier.ts';
+export * from './diff-engine.ts';
+export * from './impact-scanner.ts';
+export * from './services.ts';

package/packages/verification/src/services.ts

@@ -0,0 +1,238 @@
+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');
+  }
+}