docorbit 0.1.0

package/packages/verification/src/verifier.ts

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

package/packages/workspace/src/detector.ts

@@ -0,0 +1,143 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import type {
+  Ecosystem,
+  ProjectDependency,
+  WorkspaceScanResult,
+} from '../../shared/src/index.ts';
+import {
+  type EcosystemStrategy,
+  getDefaultStrategies,
+} from './ecosystems/index.ts';
+
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.docorbit',
+  'dist',
+  'build',
+  'target',
+  'vendor',
+  '.venv',
+  'venv',
+  '.next',
+  '.turbo',
+]);
+
+/**
+ * Recursively locates files in a directory up to a max depth, skipping ignored folders.
+ */
+function findManifestFiles(
+  dir: string,
+  targetFileNames: Set<string>,
+  maxDepth: number = 4,
+  currentDepth: number = 0
+): string[] {
+  if (currentDepth > maxDepth) return [];
+  const results: string[] = [];
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (IGNORED_DIRS.has(entry.name)) continue;
+
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...findManifestFiles(fullPath, targetFileNames, maxDepth, currentDepth + 1));
+      } else if (entry.isFile()) {
+        const name = entry.name.toLowerCase();
+        if (targetFileNames.has(name)) {
+          results.push(fullPath);
+        }
+      }
+    }
+  } catch {
+    // Directory unreadable, ignore
+  }
+
+  return results;
+}
+
+/**
+ * Scans a workspace directory, detects package manifests across supported ecosystems,
+ * correlates lockfiles with resolved versions, and preserves monorepo boundaries.
+ */
+export function detectWorkspaceDependencies(
+  workspaceDir: string,
+  strategies: EcosystemStrategy[] = getDefaultStrategies()
+): WorkspaceScanResult {
+  // Index strategies by manifest and lockfile names
+  const manifestMap = new Map<string, EcosystemStrategy>();
+  const lockfileMap = new Map<string, EcosystemStrategy>();
+  const allTargetNames = new Set<string>();
+
+  for (const strat of strategies) {
+    for (const mName of strat.manifestNames) {
+      const lower = mName.toLowerCase();
+      manifestMap.set(lower, strat);
+      allTargetNames.add(lower);
+    }
+    if (strat.lockfileNames) {
+      for (const lName of strat.lockfileNames) {
+        const lower = lName.toLowerCase();
+        lockfileMap.set(lower, strat);
+        allTargetNames.add(lower);
+      }
+    }
+  }
+
+  const manifests = findManifestFiles(workspaceDir, allTargetNames);
+  const ecosystems = new Set<Ecosystem>();
+  const dependencies: ProjectDependency[] = [];
+  const manifestsFound: string[] = [];
+
+  // 1. Gather all lockfiles first to correlate resolved versions
+  const lockfileCache = new Map<string, Map<string, string>>();
+
+  for (const file of manifests) {
+    const rel = relative(workspaceDir, file);
+    manifestsFound.push(rel);
+    const baseName = file.split(/[/\\]/).pop()?.toLowerCase() || '';
+
+    const lockStrategy = lockfileMap.get(baseName);
+    if (lockStrategy && lockStrategy.parseLockfile) {
+      try {
+        const content = readFileSync(file, 'utf-8');
+        lockfileCache.set(rel, lockStrategy.parseLockfile(baseName, content));
+      } catch {
+        // Ignore unreadable lockfile
+      }
+    }
+  }
+
+  // 2. Parse package manifests and resolve versions
+  for (const file of manifests) {
+    const rel = relative(workspaceDir, file);
+    const baseName = file.split(/[/\\]/).pop()?.toLowerCase() || '';
+    const pkgDir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '.';
+
+    const strat = manifestMap.get(baseName);
+    if (strat) {
+      try {
+        const content = readFileSync(file, 'utf-8');
+        ecosystems.add(strat.ecosystem);
+        const parsed = strat.parseManifest(baseName, content, rel, pkgDir);
+
+        if (strat.resolveVersions) {
+          strat.resolveVersions(parsed, pkgDir, lockfileCache);
+        }
+
+        dependencies.push(...parsed);
+      } catch {
+        // Ignore parse failure
+      }
+    }
+  }
+
+  return {
+    workspaceRoot: workspaceDir,
+    ecosystems: Array.from(ecosystems),
+    manifestsFound,
+    dependencies,
+  };
+}

package/packages/workspace/src/ecosystems/cargo.ts

@@ -0,0 +1,84 @@
+import { join } from 'node:path';
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class CargoStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'cargo';
+  readonly manifestNames = ['cargo.toml'];
+  readonly lockfileNames = ['cargo.lock'];
+
+  parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    let currentSection = '';
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        currentSection = trimmed.slice(1, -1).trim();
+        continue;
+      }
+
+      const isDep =
+        currentSection === 'dependencies' ||
+        currentSection === 'dev-dependencies' ||
+        currentSection === 'build-dependencies';
+
+      if (isDep && trimmed && !trimmed.startsWith('#') && trimmed.includes('=')) {
+        const eqIdx = trimmed.indexOf('=');
+        const name = trimmed.slice(0, eqIdx).trim();
+        const val = trimmed.slice(eqIdx + 1).trim();
+
+        let version = '*';
+        if (val.startsWith('"')) {
+          version = val.replace(/^"|"$/g, '');
+        } else if (val.startsWith('{')) {
+          const vMatch = val.match(/version\s*=\s*"([^"]+)"/);
+          if (vMatch) version = vMatch[1];
+        }
+
+        deps.push({
+          name,
+          ecosystem: 'cargo',
+          requestedVersion: version,
+          sourceFile: relPath,
+          packagePath: packageDir,
+          isDev: currentSection === 'dev-dependencies',
+        });
+      }
+    }
+    return deps;
+  }
+
+  parseLockfile(_fileName: string, content: string): Map<string, string> {
+    const resolved = new Map<string, string>();
+    const blocks = content.split('[[package]]');
+    for (const block of blocks) {
+      const nameMatch = block.match(/name\s*=\s*"([^"]+)"/);
+      const verMatch = block.match(/version\s*=\s*"([^"]+)"/);
+      if (nameMatch && verMatch) {
+        resolved.set(nameMatch[1], verMatch[1]);
+      }
+    }
+    return resolved;
+  }
+
+  resolveVersions(
+    deps: ProjectDependency[],
+    pkgDir: string,
+    lockfileCache: Map<string, Map<string, string>>
+  ): void {
+    const lockMap =
+      lockfileCache.get('Cargo.lock') ||
+      lockfileCache.get('cargo.lock') ||
+      lockfileCache.get(join(pkgDir, 'Cargo.lock')) ||
+      lockfileCache.get(join(pkgDir, 'cargo.lock'));
+
+    if (lockMap) {
+      for (const dep of deps) {
+        const resolved = lockMap.get(dep.name);
+        if (resolved) dep.resolvedVersion = resolved;
+      }
+    }
+  }
+}

package/packages/workspace/src/ecosystems/composer.ts

@@ -0,0 +1,42 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class ComposerStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'composer';
+  readonly manifestNames = ['composer.json'];
+
+  parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    try {
+      const composer = JSON.parse(content);
+      if (composer.require && typeof composer.require === 'object') {
+        for (const [name, ver] of Object.entries(composer.require)) {
+          if (name === 'php') continue;
+          deps.push({
+            name,
+            ecosystem: 'composer',
+            requestedVersion: String(ver),
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev: false,
+          });
+        }
+      }
+      if (composer['require-dev'] && typeof composer['require-dev'] === 'object') {
+        for (const [name, ver] of Object.entries(composer['require-dev'])) {
+          deps.push({
+            name,
+            ecosystem: 'composer',
+            requestedVersion: String(ver),
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev: true,
+          });
+        }
+      }
+    } catch {
+      // Ignore malformed JSON
+    }
+    return deps;
+  }
+}

package/packages/workspace/src/ecosystems/go.ts

@@ -0,0 +1,54 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class GoStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'go';
+  readonly manifestNames = ['go.mod'];
+
+  parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    const lines = content.split('\n');
+    let inRequireBlock = false;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('require (')) {
+        inRequireBlock = true;
+        continue;
+      }
+      if (inRequireBlock && trimmed === ')') {
+        inRequireBlock = false;
+        continue;
+      }
+
+      if (inRequireBlock && trimmed && !trimmed.startsWith('//')) {
+        const parts = trimmed.split(/\s+/);
+        if (parts.length >= 2) {
+          deps.push({
+            name: parts[0],
+            ecosystem: 'go',
+            requestedVersion: parts[1],
+            resolvedVersion: parts[1].replace(/^\+incompatible$/, ''),
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev: false,
+          });
+        }
+      } else if (trimmed.startsWith('require ') && !trimmed.includes('(')) {
+        const parts = trimmed.slice('require '.length).trim().split(/\s+/);
+        if (parts.length >= 2) {
+          deps.push({
+            name: parts[0],
+            ecosystem: 'go',
+            requestedVersion: parts[1],
+            resolvedVersion: parts[1].replace(/^\+incompatible$/, ''),
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev: false,
+          });
+        }
+      }
+    }
+    return deps;
+  }
+}