docorbit 0.1.0 → 0.1.2

package/packages/storage/src/repository.ts

@@ -1,256 +0,0 @@
-import type {
-  DiscoveredSource,
-  NormalizedPage,
-  DocumentChunk,
-  ChunkCode,
-  SymbolReference,
-  ChunkRelationship,
-  ChunkType,
-  ApiEndpoint,
-  IndexedExample,
-  Pitfall,
-  PitfallKind,
-} from '../../shared/src/index.ts';
-import type { DocOrbitDb } from './db.ts';
-import type {
-  Snapshot,
-  ISourceRepository,
-  IPageRepository,
-  IChunkRepository,
-  IApiRepository,
-  IExampleRepository,
-  IPitfallRepository,
-} from './interfaces.ts';
-import { SourceRepository } from './repositories/source-repository.ts';
-import { PageRepository } from './repositories/page-repository.ts';
-import { ChunkRepository } from './repositories/chunk-repository.ts';
-import { ApiRepository } from './repositories/api-repository.ts';
-import { ExampleRepository } from './repositories/example-repository.ts';
-import { PitfallRepository } from './repositories/pitfall-repository.ts';
-
-export type { Snapshot } from './interfaces.ts';
-
-/**
- * Unified Facade for the DocOrbit database storage layer.
- * Delegates domain responsibilities to specialized sub-repositories:
- * - sources: ISourceRepository (sources, snapshots, snapshot-page links)
- * - pages: IPageRepository (normalized pages, page links, page FTS)
- * - chunks: IChunkRepository (document chunks, code, symbols, relationships, chunk FTS)
- * - apis: IApiRepository (API endpoints, OpenAPI schemas, endpoint FTS)
- * - examples: IExampleRepository (code examples, example FTS)
- * - pitfalls: IPitfallRepository (pitfalls, gotchas, pitfall FTS)
- */
-export class DocOrbitRepository
-  implements
-    ISourceRepository,
-    IPageRepository,
-    IChunkRepository,
-    IApiRepository,
-    IExampleRepository,
-    IPitfallRepository
-{
-  public readonly sources: SourceRepository;
-  public readonly pages: PageRepository;
-  public readonly chunks: ChunkRepository;
-  public readonly apis: ApiRepository;
-  public readonly examples: ExampleRepository;
-  public readonly pitfalls: PitfallRepository;
-
-  public readonly db: DocOrbitDb;
-
-  constructor(db: DocOrbitDb) {
-    this.db = db;
-    this.pages = new PageRepository(db);
-    this.sources = new SourceRepository(db, row => this.pages.hydratePage(row));
-    this.chunks = new ChunkRepository(db);
-    this.apis = new ApiRepository(db);
-    this.examples = new ExampleRepository(db);
-    this.pitfalls = new PitfallRepository(db);
-  }
-
-  // --- ISourceRepository Delegations ---
-
-  saveSource(source: DiscoveredSource): string {
-    return this.sources.saveSource(source);
-  }
-
-  getSource(id: string): DiscoveredSource | null {
-    return this.sources.getSource(id);
-  }
-
-  getSourceByUrl(url: string): DiscoveredSource | null {
-    return this.sources.getSourceByUrl(url);
-  }
-
-  listSources(): DiscoveredSource[] {
-    return this.sources.listSources();
-  }
-
-  createSnapshot(sourceId: string, metadata?: Record<string, unknown>, docVersion?: string): string {
-    return this.sources.createSnapshot(sourceId, metadata, docVersion);
-  }
-
-  saveSnapshot(snapshot: Snapshot): void {
-    this.sources.saveSnapshot(snapshot);
-  }
-
-  getSnapshot(id: string): Snapshot | null {
-    return this.sources.getSnapshot(id);
-  }
-
-  getLatestSnapshot(sourceId: string): Snapshot | null {
-    return this.sources.getLatestSnapshot(sourceId);
-  }
-
-  listSnapshots(sourceId: string): Snapshot[] {
-    return this.sources.listSnapshots(sourceId);
-  }
-
-  linkSnapshotPages(snapshotId: string, pageIds: string[]): void {
-    this.sources.linkSnapshotPages(snapshotId, pageIds);
-  }
-
-  getSnapshotPages(snapshotId: string): NormalizedPage[] {
-    return this.sources.getSnapshotPages(snapshotId);
-  }
-
-  // --- IPageRepository Delegations ---
-
-  savePage(page: NormalizedPage): void {
-    this.pages.savePage(page);
-  }
-
-  getPage(id: string): NormalizedPage | null {
-    return this.pages.getPage(id);
-  }
-
-  getPageByUrl(normalizedUrl: string): NormalizedPage | null {
-    return this.pages.getPageByUrl(normalizedUrl);
-  }
-
-  listPages(limit?: number, offset?: number): NormalizedPage[] {
-    return this.pages.listPages(limit, offset);
-  }
-
-  countPages(sourceId?: string): number {
-    return this.pages.countPages(sourceId);
-  }
-
-  savePageLinks(pageId: string, targetUrls: string[]): void {
-    this.pages.savePageLinks(pageId, targetUrls);
-  }
-
-  getPageLinks(pageId: string): string[] {
-    return this.pages.getPageLinks(pageId);
-  }
-
-  searchPagesFts(query: string, limit: number = 10): NormalizedPage[] {
-    return this.pages.searchPagesFts(query, limit);
-  }
-
-  // --- IChunkRepository Delegations ---
-
-  saveChunks(
-    chunks: DocumentChunk[],
-    relationships: ChunkRelationship[] = [],
-    codeSnippets: ChunkCode[] = [],
-    symbols: SymbolReference[] = []
-  ): void {
-    this.chunks.saveChunks(chunks, relationships, codeSnippets, symbols);
-  }
-
-  getChunk(id: string): DocumentChunk | null {
-    return this.chunks.getChunk(id);
-  }
-
-  getChunksByPage(pageId: string): DocumentChunk[] {
-    return this.chunks.getChunksByPage(pageId);
-  }
-
-  getChunksBySnapshot(snapshotId: string): DocumentChunk[] {
-    return this.chunks.getChunksBySnapshot(snapshotId);
-  }
-
-  getChunksByVersion(docVersion: string): DocumentChunk[] {
-    return this.chunks.getChunksByVersion(docVersion);
-  }
-
-  getChunkCode(chunkId: string): ChunkCode[] {
-    return this.chunks.getChunkCode(chunkId);
-  }
-
-  getChunkSymbols(chunkId: string): SymbolReference[] {
-    return this.chunks.getChunkSymbols(chunkId);
-  }
-
-  getChunkRelationships(chunkId: string): ChunkRelationship[] {
-    return this.chunks.getChunkRelationships(chunkId);
-  }
-
-  countChunks(snapshotId?: string): number {
-    return this.chunks.countChunks(snapshotId);
-  }
-
-  searchChunksFts(
-    query: string,
-    options: { limit?: number; snapshotId?: string; chunkType?: ChunkType; docVersion?: string } = {}
-  ): Array<{ chunk: DocumentChunk; ftsRank: number; symbols: SymbolReference[]; codeSnippets: ChunkCode[] }> {
-    return this.chunks.searchChunksFts(query, options);
-  }
-
-  // --- IApiRepository Delegations ---
-
-  saveApiEndpoints(endpoints: ApiEndpoint[]): void {
-    this.apis.saveApiEndpoints(endpoints);
-  }
-
-  getApiEndpoint(id: string): ApiEndpoint | null {
-    return this.apis.getApiEndpoint(id);
-  }
-
-  getApiEndpointsBySnapshot(snapshotId: string): ApiEndpoint[] {
-    return this.apis.getApiEndpointsBySnapshot(snapshotId);
-  }
-
-  searchApiEndpoints(
-    query: string,
-    options: { method?: string; docVersion?: string; limit?: number } = {}
-  ): ApiEndpoint[] {
-    return this.apis.searchApiEndpoints(query, options);
-  }
-
-  // --- IExampleRepository Delegations ---
-
-  saveIndexedExamples(examples: IndexedExample[]): void {
-    this.examples.saveIndexedExamples(examples);
-  }
-
-  getIndexedExamplesBySnapshot(snapshotId: string): IndexedExample[] {
-    return this.examples.getIndexedExamplesBySnapshot(snapshotId);
-  }
-
-  searchIndexedExamples(
-    query: string,
-    options: { language?: string; framework?: string; docVersion?: string; limit?: number } = {}
-  ): IndexedExample[] {
-    return this.examples.searchIndexedExamples(query, options);
-  }
-
-  // --- IPitfallRepository Delegations ---
-
-  savePitfalls(pitfalls: Pitfall[]): void {
-    this.pitfalls.savePitfalls(pitfalls);
-  }
-
-  getPitfallsBySnapshot(snapshotId: string): Pitfall[] {
-    return this.pitfalls.getPitfallsBySnapshot(snapshotId);
-  }
-
-  searchPitfalls(
-    query: string,
-    options: { kind?: PitfallKind; docVersion?: string; limit?: number } = {}
-  ): Pitfall[] {
-    return this.pitfalls.searchPitfalls(query, options);
-  }
-}
-

package/packages/storage/src/search-tokens.ts

@@ -1,28 +0,0 @@
-export const SEARCH_STOPWORDS = new Set([
-  'a', 'about', 'above', 'after', 'again', 'against', 'all', 'am', 'an', 'and', 'any', 'are',
-  'as', 'at', 'be', 'because', 'been', 'before', 'being', 'below', 'between', 'both', 'but', 'by',
-  'can', 'did', 'do', 'does', 'doing', 'down', 'during', 'each', 'few', 'for', 'from',
-  'further', 'had', 'has', 'have', 'having', 'he', 'her', 'here', 'hers', 'herself', 'him',
-  'himself', 'his', 'how', 'i', 'if', 'in', 'into', 'is', 'it', 'its', 'itself', 'just',
-  'me', 'more', 'most', 'my', 'myself', 'no', 'nor', 'not', 'now', 'of', 'off', 'on',
-  'once', 'only', 'or', 'other', 'our', 'ours', 'ourselves', 'out', 'over', 'own', 'same',
-  'she', 'should', 'so', 'some', 'such', 'than', 'that', 'the', 'their', 'theirs', 'them',
-  'themselves', 'then', 'there', 'these', 'they', 'this', 'those', 'through', 'to', 'too',
-  'under', 'until', 'up', 'very', 'was', 'we', 'were', 'what', 'when', 'where', 'which',
-  'while', 'who', 'whom', 'why', 'with', 'you', 'your', 'yours', 'yourself', 'yourselves'
-]);
-
-/**
- * Extracts substantive tokens from query text, filtering out common stopwords
- * and short words (< 3 chars), while falling back to short words if query has no substantive words.
- */
-export function extractSearchTokens(text: string): string[] {
-  const words = text
-    .replace(/[^\w\s-]/g, ' ')
-    .trim()
-    .split(/\s+/)
-    .filter(w => w.length > 0);
-
-  const substantive = words.filter(w => w.length >= 3 && !SEARCH_STOPWORDS.has(w.toLowerCase()));
-  return substantive.length > 0 ? substantive : words.filter(w => w.length >= 2);
-}

package/packages/verification/src/diff-engine.ts

@@ -1,258 +0,0 @@
-import type {
-  ApiEndpoint,
-  DocDiffResult,
-  EndpointDiffItem,
-  Pitfall,
-} from '../../shared/src/index.ts';
-import type { DocOrbitRepository } from '../../storage/src/index.ts';
-
-export interface DiffOptions {
-  fromVersion?: string;
-  toVersion?: string;
-  fromSnapshotId?: string;
-  toSnapshotId?: string;
-  sourceId?: string;
-}
-
-export class DocDiffEngine {
-  private repo: DocOrbitRepository;
-
-  constructor(repo: DocOrbitRepository) {
-    this.repo = repo;
-  }
-
-  diff(options: DiffOptions): DocDiffResult {
-    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: EndpointDiffItem[] = [];
-    const fromMap = new Map<string, ApiEndpoint>();
-    const toMap = new Map<string, ApiEndpoint>();
-
-    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: Array<{ changeType: 'added' | 'removed'; pitfall: Pitfall }> = [];
-    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(),
-    };
-  }
-
-  private getEndpoints(snapshotId?: string, docVersion?: string): ApiEndpoint[] {
-    if (snapshotId) {
-      return this.repo.getApiEndpointsBySnapshot(snapshotId);
-    }
-    return this.repo.searchApiEndpoints('', {
-      docVersion,
-      limit: 500,
-    });
-  }
-
-  private getPitfalls(snapshotId?: string, docVersion?: string): Pitfall[] {
-    if (snapshotId) {
-      return this.repo.getPitfallsBySnapshot(snapshotId);
-    }
-    return this.repo.searchPitfalls('', {
-      docVersion,
-      limit: 200,
-    });
-  }
-
-  private detectEndpointModifications(fromEp: ApiEndpoint, toEp: ApiEndpoint): string[] {
-    const changes: string[] = [];
-
-    // 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;
-  }
-
-  private computeContentDiffs(options: DiffOptions): Array<{ title: string; changeType: 'added' | 'removed' | 'modified'; summary: string }> {
-    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: Array<{ title: string; changeType: 'added' | 'removed' | 'modified'; summary: string }> = [];
-    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;
-  }
-}