docorbit 0.1.0 → 0.1.2

package/dist/packages/verification/src/diff-engine.js

@@ -0,0 +1,218 @@
+export class DocDiffEngine {
+    repo;
+    constructor(repo) {
+        this.repo = repo;
+    }
+    diff(options) {
+        const fromEndpoints = this.getEndpoints(options.fromSnapshotId, options.fromVersion);
+        const toEndpoints = this.getEndpoints(options.toSnapshotId, options.toVersion);
+        const fromPitfalls = this.getPitfalls(options.fromSnapshotId, options.fromVersion);
+        const toPitfalls = this.getPitfalls(options.toSnapshotId, options.toVersion);
+        // 1. Compute Endpoint Diffs
+        const apiChanges = [];
+        const fromMap = new Map();
+        const toMap = new Map();
+        for (const ep of fromEndpoints) {
+            fromMap.set(`${ep.method.toUpperCase()} ${ep.path}`, ep);
+        }
+        for (const ep of toEndpoints) {
+            toMap.set(`${ep.method.toUpperCase()} ${ep.path}`, ep);
+        }
+        let addedCount = 0;
+        let removedCount = 0;
+        let modifiedCount = 0;
+        let deprecatedCount = 0;
+        // Check additions, deprecations, and modifications in 'to'
+        for (const [key, toEp] of toMap.entries()) {
+            const fromEp = fromMap.get(key);
+            if (!fromEp) {
+                // Newly added endpoint
+                apiChanges.push({
+                    path: toEp.path,
+                    method: toEp.method,
+                    changeType: 'added',
+                    endpoint: toEp,
+                });
+                addedCount++;
+            }
+            else {
+                // Existed previously: check deprecation status
+                if (toEp.deprecated && !fromEp.deprecated) {
+                    apiChanges.push({
+                        path: toEp.path,
+                        method: toEp.method,
+                        changeType: 'deprecated',
+                        endpoint: toEp,
+                        previousEndpoint: fromEp,
+                    });
+                    deprecatedCount++;
+                }
+                // Check semantic parameter and schema modifications
+                const changes = this.detectEndpointModifications(fromEp, toEp);
+                if (changes.length > 0) {
+                    apiChanges.push({
+                        path: toEp.path,
+                        method: toEp.method,
+                        changeType: 'modified',
+                        changes,
+                        endpoint: toEp,
+                        previousEndpoint: fromEp,
+                    });
+                    modifiedCount++;
+                }
+            }
+        }
+        // Check removals from 'from'
+        for (const [key, fromEp] of fromMap.entries()) {
+            if (!toMap.has(key)) {
+                apiChanges.push({
+                    path: fromEp.path,
+                    method: fromEp.method,
+                    changeType: 'removed',
+                    endpoint: fromEp,
+                });
+                removedCount++;
+            }
+        }
+        // 2. Compute Pitfall Diffs
+        const pitfallChanges = [];
+        const fromPitfallTitles = new Set(fromPitfalls.map(p => `${p.kind}:${p.title}`));
+        const toPitfallTitles = new Set(toPitfalls.map(p => `${p.kind}:${p.title}`));
+        for (const toP of toPitfalls) {
+            if (!fromPitfallTitles.has(`${toP.kind}:${toP.title}`)) {
+                pitfallChanges.push({ changeType: 'added', pitfall: toP });
+            }
+        }
+        for (const fromP of fromPitfalls) {
+            if (!toPitfallTitles.has(`${fromP.kind}:${fromP.title}`)) {
+                pitfallChanges.push({ changeType: 'removed', pitfall: fromP });
+            }
+        }
+        // 3. Compute Content/Chunk Diffs (Semantic only, ignoring formatting-only whitespace)
+        const contentChanges = this.computeContentDiffs(options);
+        return {
+            fromVersion: options.fromVersion,
+            toVersion: options.toVersion,
+            fromSnapshotId: options.fromSnapshotId,
+            toSnapshotId: options.toSnapshotId,
+            sourceId: options.sourceId,
+            summary: {
+                endpointsAdded: addedCount,
+                endpointsRemoved: removedCount,
+                endpointsModified: modifiedCount,
+                endpointsDeprecated: deprecatedCount,
+                pitfallsAdded: pitfallChanges.filter(p => p.changeType === 'added').length,
+                pitfallsRemoved: pitfallChanges.filter(p => p.changeType === 'removed').length,
+                contentChanged: contentChanges.length,
+            },
+            apiChanges,
+            pitfallChanges,
+            contentChanges,
+            retrievedAt: new Date().toISOString(),
+        };
+    }
+    getEndpoints(snapshotId, docVersion) {
+        if (snapshotId) {
+            return this.repo.getApiEndpointsBySnapshot(snapshotId);
+        }
+        return this.repo.searchApiEndpoints('', {
+            docVersion,
+            limit: 500,
+        });
+    }
+    getPitfalls(snapshotId, docVersion) {
+        if (snapshotId) {
+            return this.repo.getPitfallsBySnapshot(snapshotId);
+        }
+        return this.repo.searchPitfalls('', {
+            docVersion,
+            limit: 200,
+        });
+    }
+    detectEndpointModifications(fromEp, toEp) {
+        const changes = [];
+        // Compare parameters
+        const fromParams = new Map(fromEp.parameters.map(p => [p.name, p]));
+        const toParams = new Map(toEp.parameters.map(p => [p.name, p]));
+        for (const [name, toP] of toParams.entries()) {
+            const fromP = fromParams.get(name);
+            if (!fromP) {
+                changes.push(`Added parameter "${name}"${toP.required ? ' (required)' : ''}`);
+            }
+            else if (!fromP.required && toP.required) {
+                changes.push(`Parameter "${name}" is now required (was optional)`);
+            }
+            else if (fromP.type !== toP.type && toP.type) {
+                changes.push(`Parameter "${name}" type changed from ${fromP.type || 'any'} to ${toP.type}`);
+            }
+        }
+        for (const name of fromParams.keys()) {
+            if (!toParams.has(name)) {
+                changes.push(`Removed parameter "${name}"`);
+            }
+        }
+        // Compare Request Body required fields
+        const fromReq = new Set(fromEp.requestSchema?.required || []);
+        const toReq = new Set(toEp.requestSchema?.required || []);
+        for (const field of toReq) {
+            if (!fromReq.has(field)) {
+                changes.push(`Request body field "${field}" is now required`);
+            }
+        }
+        for (const field of fromReq) {
+            if (!toReq.has(field)) {
+                changes.push(`Request body field "${field}" is no longer required`);
+            }
+        }
+        return changes;
+    }
+    computeContentDiffs(options) {
+        const fromChunks = options.fromSnapshotId
+            ? this.repo.getChunksBySnapshot(options.fromSnapshotId)
+            : options.fromVersion
+                ? this.repo.getChunksByVersion(options.fromVersion)
+                : [];
+        const toChunks = options.toSnapshotId
+            ? this.repo.getChunksBySnapshot(options.toSnapshotId)
+            : options.toVersion
+                ? this.repo.getChunksByVersion(options.toVersion)
+                : [];
+        if (fromChunks.length === 0 && toChunks.length === 0)
+            return [];
+        const changes = [];
+        const fromMap = new Map(fromChunks.map(c => [c.title, c]));
+        const toMap = new Map(toChunks.map(c => [c.title, c]));
+        for (const [title, toC] of toMap.entries()) {
+            const fromC = fromMap.get(title);
+            if (!fromC) {
+                changes.push({
+                    title,
+                    changeType: 'added',
+                    summary: `New documentation section: "${title}"`,
+                });
+            }
+            else if (fromC.contentHash !== toC.contentHash) {
+                // Compare normalized text to ignore formatting-only whitespace
+                const normFrom = fromC.content.replace(/\s+/g, ' ').trim();
+                const normTo = toC.content.replace(/\s+/g, ' ').trim();
+                if (normFrom !== normTo) {
+                    changes.push({
+                        title,
+                        changeType: 'modified',
+                        summary: `Content updated for section "${title}"`,
+                    });
+                }
+            }
+        }
+        for (const title of fromMap.keys()) {
+            if (!toMap.has(title)) {
+                changes.push({
+                    title,
+                    changeType: 'removed',
+                    summary: `Documentation section removed: "${title}"`,
+                });
+            }
+        }
+        return changes;
+    }
+}

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

@@ -0,0 +1,29 @@
+import type { ExtractedApiCall } from '../../shared/src/index.ts';
+/**
+ * Normalizes an API path for comparison against schema paths.
+ * E.g. extracts pathname from full URLs ("https://api.stripe.com/v1/webhook_endpoints" -> "/v1/webhook_endpoints")
+ */
+export declare function normalizeApiPath(urlOrPath: string): string;
+/**
+ * Checks if an extracted path matches an OpenAPI schema path template.
+ * E.g. candidate "/v1/webhook_endpoints/we_123" matches schema "/v1/webhook_endpoints/{id}"
+ */
+export declare function matchEndpointPath(candidatePath: string, schemaPath: string): boolean;
+/**
+ * Deterministically extracts API calls, parameters, methods, and version syntax from code.
+ */
+export declare class CodeApiExtractor {
+    /**
+     * Extracts API calls from code.
+     */
+    extract(code: string, language?: string): ExtractedApiCall[];
+    private findLineNumber;
+    private extractNextJsParams;
+    private extractFetchCalls;
+    private extractAxiosCalls;
+    private extractPythonRequestsCalls;
+    private extractCurlCalls;
+    private extractSdkCalls;
+    private extractDynamicCalls;
+    private extractResponseFields;
+}

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

@@ -0,0 +1,302 @@
+/**
+ * Normalizes an API path for comparison against schema paths.
+ * E.g. extracts pathname from full URLs ("https://api.stripe.com/v1/webhook_endpoints" -> "/v1/webhook_endpoints")
+ */
+export function normalizeApiPath(urlOrPath) {
+    try {
+        if (urlOrPath.startsWith('http://') || urlOrPath.startsWith('https://')) {
+            const parsed = new URL(urlOrPath);
+            return parsed.pathname;
+        }
+    }
+    catch {
+        // Fall back to regex
+    }
+    const match = urlOrPath.match(/^https?:\/\/[^/]+(\/.*)$/);
+    if (match)
+        return match[1].split('?')[0];
+    return urlOrPath.split('?')[0].trim();
+}
+/**
+ * Checks if an extracted path matches an OpenAPI schema path template.
+ * E.g. candidate "/v1/webhook_endpoints/we_123" matches schema "/v1/webhook_endpoints/{id}"
+ */
+export function matchEndpointPath(candidatePath, schemaPath) {
+    const normCandidate = normalizeApiPath(candidatePath).replace(/\/+$/, '');
+    const normSchema = normalizeApiPath(schemaPath).replace(/\/+$/, '');
+    if (normCandidate.toLowerCase() === normSchema.toLowerCase()) {
+        return true;
+    }
+    // Convert schema {param} or :param to regex wildcard
+    const regexPattern = normSchema
+        .replace(/{[^}]+}/g, '([^/]+)')
+        .replace(/:[a-zA-Z0-9_]+/g, '([^/]+)')
+        .replace(/\//g, '\\/');
+    const regex = new RegExp(`^${regexPattern}$`, 'i');
+    return regex.test(normCandidate);
+}
+/**
+ * Extracts top-level key names from a JS/Python object or JSON snippet string.
+ */
+function extractObjectKeys(objSnippet) {
+    const keys = new Set();
+    // Try standard JSON parse first
+    try {
+        const parsed = JSON.parse(objSnippet);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return Object.keys(parsed);
+        }
+    }
+    catch {
+        // Fall back to lexical key extraction
+    }
+    // Match identifier keys: { foo: ..., "bar": ..., 'baz': ... }
+    const keyRegex = /(?:[{,]\s*)(?:["']?([a-zA-Z0-9_-]+)["']?)\s*:/g;
+    let match;
+    while ((match = keyRegex.exec(objSnippet)) !== null) {
+        if (match[1] && !['method', 'headers', 'body'].includes(match[1])) {
+            keys.add(match[1]);
+        }
+    }
+    return Array.from(keys);
+}
+/**
+ * Deterministically extracts API calls, parameters, methods, and version syntax from code.
+ */
+export class CodeApiExtractor {
+    /**
+     * Extracts API calls from code.
+     */
+    extract(code, language) {
+        const results = [];
+        const lines = code.split('\n');
+        // 1. Check for Next.js Route Params patterns (sync vs async)
+        this.extractNextJsParams(code, lines, results);
+        // 2. Extract Fetch calls: fetch('url', { method: 'POST', body: ... })
+        this.extractFetchCalls(code, lines, results);
+        // 3. Extract Axios calls: axios.post('url', {...}) / axios.get('url')
+        this.extractAxiosCalls(code, lines, results);
+        // 4. Extract Python Requests calls: requests.post('url', json={...})
+        this.extractPythonRequestsCalls(code, lines, results);
+        // 5. Extract cURL commands: curl -X POST ...
+        this.extractCurlCalls(code, lines, results);
+        // 6. Extract common SDK calls: stripe.webhookEndpoints.create({...}), etc.
+        this.extractSdkCalls(code, lines, results);
+        // 7. Check for dynamic / unresolvable URLs: e.g. fetch(apiUrl) or axios.get(endpoint)
+        this.extractDynamicCalls(code, lines, results);
+        // If nothing was extracted at all, create an ambiguous marker
+        if (results.length === 0) {
+            results.push({
+                rawSnippet: code.slice(0, 150),
+                isDynamicOrAmbiguous: true,
+                reasonIfAmbiguous: language && !['javascript', 'typescript', 'python', 'curl', 'bash'].includes(language.toLowerCase())
+                    ? `Language "${language}" is not currently supported for deep AST schema verification.`
+                    : 'No recognizable HTTP/API client calls, SDK invocations, or endpoint paths found in code.',
+                language,
+            });
+        }
+        return results;
+    }
+    findLineNumber(lines, snippetPattern) {
+        const clean = snippetPattern.trim().split('\n')[0].slice(0, 40);
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].includes(clean))
+                return i + 1;
+        }
+        return 1;
+    }
+    extractNextJsParams(code, lines, results) {
+        // Next.js 14 sync: params.slug, const { slug } = params
+        const syncParamRegex = /(?:const\s+{\s*([^}]+)\s*}\s*=\s*params\b|\bparams\.([a-zA-Z0-9_]+))/;
+        // Next.js 15+ async: await params, const { slug } = await params
+        const asyncParamRegex = /(?:await\s+params\b|const\s+{\s*([^}]+)\s*}\s*=\s*await\s+params\b)/;
+        const hasAsync = asyncParamRegex.test(code);
+        const hasSync = syncParamRegex.test(code) && !hasAsync;
+        if (hasAsync) {
+            const match = code.match(asyncParamRegex);
+            results.push({
+                symbol: 'nextjs_route_params_async',
+                endpointPath: 'nextjs/app_router/params',
+                method: 'get',
+                rawSnippet: match ? match[0] : 'await params',
+                line: match ? this.findLineNumber(lines, match[0]) : 1,
+            });
+        }
+        else if (hasSync) {
+            const match = code.match(syncParamRegex);
+            results.push({
+                symbol: 'nextjs_route_params_sync',
+                endpointPath: 'nextjs/app_router/params',
+                method: 'get',
+                rawSnippet: match ? match[0] : 'params.slug',
+                line: match ? this.findLineNumber(lines, match[0]) : 1,
+            });
+        }
+    }
+    extractFetchCalls(code, lines, results) {
+        // Matches: fetch(['"`]([^'"`]+)['"`](?:\s*,\s*({[\s\S]*?}))?\s*\)
+        const fetchRegex = /fetch\s*\(\s*['"`]([^'"`]+)['"`](?:\s*,\s*({[\s\S]*?}))?\s*\)/g;
+        let match;
+        while ((match = fetchRegex.exec(code)) !== null) {
+            const url = match[1];
+            const optionsSnippet = match[2] || '';
+            const endpointPath = normalizeApiPath(url);
+            let method = 'get';
+            const methodMatch = optionsSnippet.match(/method\s*:\s*['"]([a-zA-Z]+)['"]/i);
+            if (methodMatch) {
+                method = methodMatch[1].toLowerCase();
+            }
+            // Extract body fields if body: JSON.stringify({...}) or body: {...}
+            let bodyFields = [];
+            const bodyMatch = optionsSnippet.match(/body\s*:\s*(?:JSON\.stringify\s*\(\s*)?({[\s\S]*?})(?:\s*\))?/);
+            if (bodyMatch) {
+                bodyFields = extractObjectKeys(bodyMatch[1]);
+            }
+            // Extract response fields accessed: e.g. data.foo, res.json()
+            const responseFields = this.extractResponseFields(code, endpointPath);
+            results.push({
+                endpointPath,
+                method,
+                bodyFields,
+                responseFieldsAccessed: responseFields,
+                rawSnippet: match[0],
+                line: this.findLineNumber(lines, match[0]),
+                language: 'javascript',
+            });
+        }
+    }
+    extractAxiosCalls(code, lines, results) {
+        // Matches: axios.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`](?:\s*,\s*({[\s\S]*?}))?/g
+        const axiosRegex = /axios\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`](?:\s*,\s*({[\s\S]*?}))?/g;
+        let match;
+        while ((match = axiosRegex.exec(code)) !== null) {
+            const method = match[1].toLowerCase();
+            const url = match[2];
+            const payloadSnippet = match[3] || '';
+            const endpointPath = normalizeApiPath(url);
+            const bodyFields = payloadSnippet ? extractObjectKeys(payloadSnippet) : [];
+            const responseFields = this.extractResponseFields(code, endpointPath);
+            results.push({
+                endpointPath,
+                method,
+                bodyFields,
+                responseFieldsAccessed: responseFields,
+                rawSnippet: match[0],
+                line: this.findLineNumber(lines, match[0]),
+                language: 'javascript',
+            });
+        }
+    }
+    extractPythonRequestsCalls(code, lines, results) {
+        // Matches: requests.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"](?:\s*,\s*(?:json|data)\s*=\s*({[\s\S]*?}))?
+        const requestsRegex = /requests\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"](?:\s*,\s*(?:json|data|params)\s*=\s*({[\s\S]*?}))?/g;
+        let match;
+        while ((match = requestsRegex.exec(code)) !== null) {
+            const method = match[1].toLowerCase();
+            const url = match[2];
+            const payloadSnippet = match[3] || '';
+            const endpointPath = normalizeApiPath(url);
+            const bodyFields = payloadSnippet ? extractObjectKeys(payloadSnippet) : [];
+            results.push({
+                endpointPath,
+                method,
+                bodyFields,
+                rawSnippet: match[0],
+                line: this.findLineNumber(lines, match[0]),
+                language: 'python',
+            });
+        }
+    }
+    extractCurlCalls(code, lines, results) {
+        // Matches: curl ... https://... -X POST -d '{...}'
+        const curlRegex = /curl\s+([^\n]+)/g;
+        let match;
+        while ((match = curlRegex.exec(code)) !== null) {
+            const fullCmd = match[1];
+            const urlMatch = fullCmd.match(/https?:\/\/[^\s'"]+/);
+            if (!urlMatch)
+                continue;
+            const endpointPath = normalizeApiPath(urlMatch[0]);
+            let method = 'get';
+            const methodMatch = fullCmd.match(/-X\s+([A-Z]+)/i);
+            if (methodMatch) {
+                method = methodMatch[1].toLowerCase();
+            }
+            else if (fullCmd.includes('-d ') || fullCmd.includes('--data')) {
+                method = 'post';
+            }
+            let bodyFields = [];
+            const dataMatch = fullCmd.match(/(?:-d|--data(?:-raw)?)\s+['"]({[\s\S]*?})['"]/);
+            if (dataMatch) {
+                bodyFields = extractObjectKeys(dataMatch[1]);
+            }
+            results.push({
+                endpointPath,
+                method,
+                bodyFields,
+                rawSnippet: match[0],
+                line: this.findLineNumber(lines, match[0]),
+                language: 'curl',
+            });
+        }
+    }
+    extractSdkCalls(code, lines, results) {
+        // Stripe SDK: stripe.webhookEndpoints.create({...})
+        const stripeWebhookRegex = /stripe\.webhookEndpoints\.create\s*\(\s*({[\s\S]*?})\s*\)/g;
+        let match;
+        while ((match = stripeWebhookRegex.exec(code)) !== null) {
+            const bodyFields = extractObjectKeys(match[1]);
+            results.push({
+                endpointPath: '/v1/webhook_endpoints',
+                method: 'post',
+                symbol: 'stripe.webhookEndpoints.create',
+                bodyFields,
+                rawSnippet: match[0],
+                line: this.findLineNumber(lines, match[0]),
+            });
+        }
+        // Stripe SDK: stripe.charges.create({...})
+        const stripeChargesRegex = /stripe\.charges\.create\s*\(\s*({[\s\S]*?})\s*\)/g;
+        while ((match = stripeChargesRegex.exec(code)) !== null) {
+            const bodyFields = extractObjectKeys(match[1]);
+            results.push({
+                endpointPath: '/v1/charges',
+                method: 'post',
+                symbol: 'stripe.charges.create',
+                bodyFields,
+                rawSnippet: match[0],
+                line: this.findLineNumber(lines, match[0]),
+            });
+        }
+    }
+    extractDynamicCalls(code, lines, results) {
+        // Matches fetch(dynamicVar) or axios.get(dynamicVar) where argument does not start with string quote
+        const dynamicFetch = /fetch\s*\(\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?:,|\))/g;
+        let match;
+        while ((match = dynamicFetch.exec(code)) !== null) {
+            const varName = match[1];
+            // Check if variable is defined as a string literal above
+            const defRegex = new RegExp(`(?:const|let|var)\\s+${varName}\\s*=\\s*['"\`]([^'"\`]+)['"\`]`);
+            if (!defRegex.test(code)) {
+                results.push({
+                    rawSnippet: match[0],
+                    isDynamicOrAmbiguous: true,
+                    reasonIfAmbiguous: `Dynamic variable "${varName}" passed to fetch() cannot be statically resolved to an API path.`,
+                    line: this.findLineNumber(lines, match[0]),
+                });
+            }
+        }
+    }
+    extractResponseFields(code, _endpoint) {
+        const fields = new Set();
+        // Matches res.data.fieldName or data.fieldName or json.fieldName or event.fieldName
+        const fieldRegex = /(?:res(?:ponse)?(?:\.data)?|data|json|body|payload)\.([a-zA-Z0-9_]+)/g;
+        let m;
+        while ((m = fieldRegex.exec(code)) !== null) {
+            if (m[1] && !['json', 'status', 'headers', 'data', 'text'].includes(m[1])) {
+                fields.add(m[1]);
+            }
+        }
+        return Array.from(fields);
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { DocDiffResult, ImpactAnalysisResult } from '../../shared/src/index.ts';
+export declare class WorkspaceImpactScanner {
+    /**
+     * Scans a workspace project directory and identifies files affected by documentation diffs.
+     */
+    scan(projectDir: string, diff: DocDiffResult): ImpactAnalysisResult;
+    private collectFiles;
+    private analyzeFile;
+}