docorbit 0.1.0 → 0.1.2

package/dist/packages/verification/src/impact-scanner.js

@@ -0,0 +1,181 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+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, diff) {
+        const files = this.collectFiles(projectDir);
+        const affectedLocations = [];
+        for (const filePath of files) {
+            this.analyzeFile(filePath, projectDir, diff, affectedLocations);
+        }
+        const uniqueFiles = new Set(affectedLocations.map(loc => loc.filePath));
+        let summary;
+        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,
+        };
+    }
+    collectFiles(dir) {
+        const results = [];
+        if (!fs.existsSync(dir))
+            return results;
+        const traverse = (currentDir) => {
+            let entries;
+            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;
+    }
+    analyzeFile(fullPath, projectDir, diff, out) {
+        let content;
+        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();
+            // 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/dist/packages/verification/src/index.js

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

package/dist/packages/verification/src/services.d.ts

@@ -0,0 +1,55 @@
+import type { DocDiffResult, ImpactAnalysisResult, VerificationResult } from '../../shared/src/index.ts';
+import type { DocOrbitRepository } from '../../storage/src/index.ts';
+import { type DiffOptions } from './diff-engine.ts';
+export interface VerifyCodeRequest {
+    code: string;
+    language?: string;
+    library?: string;
+    version?: string;
+    projectDir?: string;
+    filePath?: string;
+}
+export declare class VerificationService {
+    private repo;
+    private extractor;
+    private verifier;
+    private resolver;
+    constructor(repo: DocOrbitRepository);
+    verifyCode(request: VerifyCodeRequest): {
+        result: VerificationResult;
+        markdown: string;
+    };
+    private synthesizeMarkdown;
+}
+export declare class DiffService {
+    private repo;
+    private diffEngine;
+    constructor(repo: DocOrbitRepository);
+    diffDocs(options: DiffOptions): {
+        result: DocDiffResult;
+        markdown: string;
+    };
+    private synthesizeMarkdown;
+}
+export declare class ImpactAnalysisService {
+    private repo?;
+    private diffService?;
+    private scanner;
+    constructor(repo?: DocOrbitRepository);
+    analyzeWorkspaceImpact(projectDir: string, diff: DocDiffResult): {
+        structured: ImpactAnalysisResult;
+        markdown: string;
+    };
+    analyzeImpact(options: {
+        projectDir: string;
+        fromVersion?: string;
+        toVersion?: string;
+        fromSnapshotId?: string;
+        toSnapshotId?: string;
+        sourceId?: string;
+    }): {
+        result: ImpactAnalysisResult;
+        markdown: string;
+    };
+    private synthesizeMarkdown;
+}

package/dist/packages/verification/src/services.js

@@ -0,0 +1,189 @@
+import { WorkspaceResolver } from "../../workspace/src/index.js";
+import { CodeApiExtractor } from "./extractor.js";
+import { SchemaVerifier } from "./verifier.js";
+import { DocDiffEngine } from "./diff-engine.js";
+import { WorkspaceImpactScanner } from "./impact-scanner.js";
+export class VerificationService {
+    repo;
+    extractor;
+    verifier;
+    resolver;
+    constructor(repo) {
+        this.repo = repo;
+        this.extractor = new CodeApiExtractor();
+        this.verifier = new SchemaVerifier(repo);
+        this.resolver = new WorkspaceResolver(repo);
+    }
+    verifyCode(request) {
+        let effectiveDocVersion = request.version;
+        let projectVersion;
+        // 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 };
+    }
+    synthesizeMarkdown(res) {
+        const lines = [];
+        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 {
+    repo;
+    diffEngine;
+    constructor(repo) {
+        this.repo = repo;
+        this.diffEngine = new DocDiffEngine(repo);
+    }
+    diffDocs(options) {
+        const result = this.diffEngine.diff(options);
+        const markdown = this.synthesizeMarkdown(result);
+        return { result, markdown };
+    }
+    synthesizeMarkdown(diff) {
+        const lines = [];
+        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 {
+    repo;
+    diffService;
+    scanner;
+    constructor(repo) {
+        this.repo = repo;
+        if (repo) {
+            this.diffService = new DiffService(repo);
+        }
+        this.scanner = new WorkspaceImpactScanner();
+    }
+    analyzeWorkspaceImpact(projectDir, diff) {
+        const structured = this.scanner.scan(projectDir, diff);
+        const markdown = this.synthesizeMarkdown(structured);
+        return { structured, markdown };
+    }
+    analyzeImpact(options) {
+        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 };
+    }
+    synthesizeMarkdown(res) {
+        const lines = [];
+        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/dist/packages/verification/src/verifier.d.ts

@@ -0,0 +1,15 @@
+import type { ExtractedApiCall, VerificationResult } from '../../shared/src/index.ts';
+import type { DocOrbitRepository } from '../../storage/src/index.ts';
+export interface VerifierOptions {
+    docVersion?: string;
+    projectVersion?: string;
+    library?: string;
+}
+export declare class SchemaVerifier {
+    private repo;
+    constructor(repo: DocOrbitRepository);
+    verify(calls: ExtractedApiCall[], options?: VerifierOptions): VerificationResult;
+    private verifyParameters;
+    private verifyResponseFields;
+    private verifyNextJsParams;
+}