docorbit 0.1.0 → 0.1.2

package/packages/workspace/src/lockfile.ts

@@ -1,194 +0,0 @@
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import type {
-  DocsLock,
-  LockedDoc,
-  WorkspaceScanResult,
-  ProjectDependency,
-  DocVersionMatch,
-} from '../../shared/src/index.ts';
-import type { DocOrbitRepository } from '../../storage/src/index.ts';
-import { resolveDocVersion } from './semver.ts';
-
-export const DOCS_LOCK_FILENAME = 'docs.lock';
-
-/**
- * Reads and parses docs.lock from a project directory if present.
- */
-export function readDocsLock(projectDir: string): DocsLock | null {
-  const filePath = join(projectDir, DOCS_LOCK_FILENAME);
-  if (!existsSync(filePath)) return null;
-
-  try {
-    const raw = readFileSync(filePath, 'utf-8');
-    const parsed = JSON.parse(raw);
-    if (parsed && parsed.version === 1 && typeof parsed.dependencies === 'object') {
-      return parsed as DocsLock;
-    }
-  } catch {
-    // Malformed lockfile
-  }
-  return null;
-}
-
-/**
- * Deterministically writes a docs.lock file to project directory.
- * Sorts dependency keys alphabetically and uses 2-space indentation.
- */
-export function writeDocsLock(projectDir: string, lock: DocsLock): void {
-  const filePath = join(projectDir, DOCS_LOCK_FILENAME);
-
-  // Sort dependency keys alphabetically
-  const sortedDeps: Record<string, LockedDoc> = {};
-  for (const key of Object.keys(lock.dependencies).sort()) {
-    sortedDeps[key] = lock.dependencies[key];
-  }
-
-  const deterministicLock: DocsLock = {
-    version: 1,
-    workspaceRoot: lock.workspaceRoot,
-    dependencies: sortedDeps,
-  };
-
-  const serialized = JSON.stringify(deterministicLock, null, 2) + '\n';
-  writeFileSync(filePath, serialized, 'utf-8');
-}
-
-/**
- * Helper to match a project dependency to an ingested source in the repository.
- */
-function findMatchingSource(dep: ProjectDependency, repo: DocOrbitRepository) {
-  const sources = repo.listSources();
-  const depClean = dep.name.toLowerCase().replace(/^@[^/]+\//, ''); // e.g. @stripe/stripe-js -> stripe-js
-
-  for (const src of sources) {
-    const srcUrl = src.url.toLowerCase();
-    // Direct match: URL or metadata contains dependency name
-    if (
-      srcUrl.includes(depClean) ||
-      srcUrl.includes(dep.name.toLowerCase()) ||
-      (src.metadata && String(src.metadata.name || '').toLowerCase() === depClean)
-    ) {
-      return src;
-    }
-  }
-  return null;
-}
-
-/**
- * Generates a DocsLock manifest from workspace scan result and repository state.
- * Preserves timestamps for unchanged documentation snapshots to prevent lockfile churn.
- */
-export function generateDocsLock(
-  scanResult: WorkspaceScanResult,
-  repo: DocOrbitRepository,
-  existingLock?: DocsLock | null
-): DocsLock {
-  const lockedDeps: Record<string, LockedDoc> = {};
-  const allSnapshots = repo.listSnapshots();
-
-  // Detect duplicate package names across monorepo packages
-  const nameCounts = new Map<string, number>();
-  for (const dep of scanResult.dependencies) {
-    nameCounts.set(dep.name, (nameCounts.get(dep.name) || 0) + 1);
-  }
-
-  for (const dep of scanResult.dependencies) {
-    // Monorepo key disambiguation
-    const isMulti = (nameCounts.get(dep.name) || 0) > 1;
-    const depKey = isMulti && dep.packagePath && dep.packagePath !== '.'
-      ? `${dep.packagePath}:${dep.name}`
-      : dep.name;
-
-    // Check if we have documentation for this dependency
-    const matchingSource = findMatchingSource(dep, repo);
-    if (!matchingSource) continue;
-
-    // Find snapshots for matching source
-    const sourceSnapshots = allSnapshots.filter(s => s.sourceId === matchingSource.id);
-    if (sourceSnapshots.length === 0) continue;
-
-    // Gather available versions from snapshots
-    const versionToSnapshot = new Map<string, typeof sourceSnapshots[0]>();
-    for (const snap of sourceSnapshots) {
-      const v = snap.docVersion || 'latest';
-      if (!versionToSnapshot.has(v)) {
-        versionToSnapshot.set(v, snap);
-      }
-    }
-
-    const availableVersions = Array.from(versionToSnapshot.keys());
-    const projectVersion = dep.resolvedVersion || dep.requestedVersion;
-    const resolution = resolveDocVersion(projectVersion, availableVersions, dep.name);
-
-    const selectedSnapshot = versionToSnapshot.get(resolution.selectedDocVersion) || sourceSnapshots[0];
-    const snapshotHash = selectedSnapshot.snapshotHash;
-
-    // Deterministic timestamp preservation:
-    // If existingLock already has this dependency with identical snapshotHash and resolvedVersion, keep the timestamp
-    const existing = existingLock?.dependencies[depKey];
-    const isUnchanged =
-      existing &&
-      existing.snapshotHash === snapshotHash &&
-      existing.resolvedDependencyVersion === (dep.resolvedVersion || dep.requestedVersion) &&
-      existing.docVersion === resolution.selectedDocVersion;
-
-    const retrievedAt = isUnchanged ? existing.retrievedAt : new Date().toISOString();
-
-    lockedDeps[depKey] = {
-      name: dep.name,
-      ecosystem: dep.ecosystem,
-      requestedVersion: dep.requestedVersion,
-      resolvedDependencyVersion: dep.resolvedVersion || dep.requestedVersion,
-      sourceFile: dep.sourceFile,
-      docSourceUrl: matchingSource.url,
-      docVersion: resolution.selectedDocVersion,
-      matchType: resolution.matchType,
-      confidence: resolution.confidence,
-      snapshotId: selectedSnapshot.id,
-      snapshotHash,
-      retrievedAt,
-    };
-  }
-
-  return {
-    version: 1,
-    workspaceRoot: scanResult.workspaceRoot,
-    dependencies: lockedDeps,
-  };
-}
-
-/**
- * Selectively or globally updates docs.lock for a project.
- */
-export function updateDocsLock(
-  scanResult: WorkspaceScanResult,
-  repo: DocOrbitRepository,
-  existingLock: DocsLock,
-  specificDependency?: string
-): DocsLock {
-  if (!specificDependency) {
-    // Full update: regenerate with existing lock as baseline for unchanged items
-    return generateDocsLock(scanResult, repo, existingLock);
-  }
-
-  // Selective update: only force refresh of specific dependency
-  const updated = generateDocsLock(scanResult, repo, existingLock);
-  const resultDeps = { ...existingLock.dependencies };
-
-  for (const [key, doc] of Object.entries(updated.dependencies)) {
-    if (doc.name === specificDependency || key === specificDependency) {
-      // Force new timestamp for the target dependency being updated
-      resultDeps[key] = {
-        ...doc,
-        retrievedAt: new Date().toISOString(),
-      };
-    }
-  }
-
-  return {
-    version: 1,
-    workspaceRoot: scanResult.workspaceRoot,
-    dependencies: resultDeps,
-  };
-}

package/packages/workspace/src/resolver.ts

@@ -1,234 +0,0 @@
-import type {
-  DocsLock,
-  ProjectDependency,
-  WorkspaceScanResult,
-  VersionResolutionResult,
-} from '../../shared/src/index.ts';
-import type { DocOrbitRepository } from '../../storage/src/index.ts';
-import { readDocsLock } from './lockfile.ts';
-import { detectWorkspaceDependencies } from './detector.ts';
-import { resolveDocVersion } from './semver.ts';
-
-export interface ResolvedProjectContext {
-  projectDir: string;
-  hasLockfile: boolean;
-  matchedDependency?: {
-    name: string;
-    projectVersion: string;
-    targetDocVersion: string;
-    targetSnapshotId?: string;
-    confidence: number;
-    matchType: string;
-  };
-  allDependencies: ProjectDependency[];
-}
-
-/**
- * Normalizes query string for token matching against dependency names.
- */
-function normalizeQueryTokens(query: string): Set<string> {
-  const tokens = query
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, ' ')
-    .split(/\s+/)
-    .filter(t => t.length > 1);
-
-  const set = new Set(tokens);
-  // Add common aliases
-  if (set.has('nextjs') || set.has('next.js')) {
-    set.add('next');
-  }
-  if (set.has('reactjs') || set.has('react.js')) {
-    set.add('react');
-  }
-  if (set.has('vuejs') || set.has('vue.js')) {
-    set.add('vue');
-  }
-  return set;
-}
-
-/**
- * Resolves project context and detects if a query targets a specific dependency in the project.
- * Uses docs.lock if present for zero-overhead deterministic pinned resolution,
- * or falls back to live manifest scanning and resolution.
- */
-export function resolveProjectContext(
-  projectDir: string,
-  query: string,
-  repo: DocOrbitRepository
-): ResolvedProjectContext {
-  const lock = readDocsLock(projectDir);
-  const queryTokens = normalizeQueryTokens(query);
-
-  if (lock) {
-    // 1. Check locked dependencies
-    for (const [key, lockedDoc] of Object.entries(lock.dependencies)) {
-      const cleanName = lockedDoc.name.toLowerCase().replace(/^@[^/]+\//, '');
-      const parts = cleanName.split(/[-_.]/);
-
-      const matches =
-        queryTokens.has(lockedDoc.name.toLowerCase()) ||
-        queryTokens.has(cleanName) ||
-        parts.some(p => p.length > 2 && queryTokens.has(p));
-
-      if (matches) {
-        return {
-          projectDir,
-          hasLockfile: true,
-          matchedDependency: {
-            name: lockedDoc.name,
-            projectVersion: lockedDoc.resolvedDependencyVersion,
-            targetDocVersion: lockedDoc.docVersion,
-            targetSnapshotId: lockedDoc.snapshotId,
-            confidence: lockedDoc.confidence,
-            matchType: lockedDoc.matchType,
-          },
-          allDependencies: Object.values(lock.dependencies).map(d => ({
-            name: d.name,
-            ecosystem: d.ecosystem,
-            requestedVersion: d.requestedVersion,
-            resolvedVersion: d.resolvedDependencyVersion,
-            sourceFile: d.sourceFile,
-          })),
-        };
-      }
-    }
-
-    return {
-      projectDir,
-      hasLockfile: true,
-      allDependencies: Object.values(lock.dependencies).map(d => ({
-        name: d.name,
-        ecosystem: d.ecosystem,
-        requestedVersion: d.requestedVersion,
-        resolvedVersion: d.resolvedDependencyVersion,
-        sourceFile: d.sourceFile,
-      })),
-    };
-  }
-
-  // 2. Fallback: scan workspace manifests directly
-  const scan = detectWorkspaceDependencies(projectDir);
-  const allSnapshots = repo.listSnapshots();
-  const allSources = repo.listSources();
-
-  for (const dep of scan.dependencies) {
-    const cleanName = dep.name.toLowerCase().replace(/^@[^/]+\//, '');
-    const parts = cleanName.split(/[-_.]/);
-
-    const matches =
-      queryTokens.has(dep.name.toLowerCase()) ||
-      queryTokens.has(cleanName) ||
-      parts.some(p => p.length > 2 && queryTokens.has(p));
-
-    if (matches) {
-      // Find matching source
-      const src = allSources.find(s => {
-        const u = s.url.toLowerCase();
-        return u.includes(cleanName) || u.includes(dep.name.toLowerCase());
-      });
-
-      if (src) {
-        const snapshots = allSnapshots.filter(s => s.sourceId === src.id);
-        const availableVersions = snapshots.map(s => s.docVersion || 'latest');
-        const projectVer = dep.resolvedVersion || dep.requestedVersion;
-        const resolution = resolveDocVersion(projectVer, availableVersions, dep.name);
-
-        const chosenSnapshot = snapshots.find(
-          s => (s.docVersion || 'latest') === resolution.selectedDocVersion
-        ) || snapshots[0];
-
-        return {
-          projectDir,
-          hasLockfile: false,
-          matchedDependency: {
-            name: dep.name,
-            projectVersion: projectVer,
-            targetDocVersion: resolution.selectedDocVersion,
-            targetSnapshotId: chosenSnapshot?.id,
-            confidence: resolution.confidence,
-            matchType: resolution.matchType,
-          },
-          allDependencies: scan.dependencies,
-        };
-      }
-    }
-  }
-
-  return {
-    projectDir,
-    hasLockfile: false,
-    allDependencies: scan.dependencies,
-  };
-}
-
-export interface WorkspaceMatch {
-  dependency: ProjectDependency;
-  targetVersion: string;
-  confidence: number;
-  snapshotId?: string;
-  matchedBy: string;
-}
-
-export interface WorkspaceResolutionSummary {
-  matches: WorkspaceMatch[];
-}
-
-export class WorkspaceResolver {
-  private repo: DocOrbitRepository;
-
-  constructor(repo: DocOrbitRepository) {
-    this.repo = repo;
-  }
-
-  resolveProjectContext(projectDir: string, query: string): ResolvedProjectContext {
-    return resolveProjectContext(projectDir, query, this.repo);
-  }
-
-  scanWorkspace(projectDir: string): WorkspaceScanResult {
-    return detectWorkspaceDependencies(projectDir);
-  }
-
-  resolveWorkspace(scan: WorkspaceScanResult, _existingLock?: DocsLock | null): WorkspaceResolutionSummary {
-    const allSnapshots = this.repo.listSnapshots();
-    const allSources = this.repo.listSources();
-    const matches: WorkspaceMatch[] = [];
-
-    for (const dep of scan.dependencies) {
-      const cleanName = dep.name.toLowerCase().replace(/^@[^/]+\//, '');
-      const src = allSources.find(s => {
-        const u = s.url.toLowerCase();
-        return u.includes(cleanName) || u.includes(dep.name.toLowerCase()) ||
-          (s.metadata && String(s.metadata.name || '').toLowerCase() === cleanName);
-      });
-
-      if (!src) continue;
-
-      const snapshots = allSnapshots.filter(s => s.sourceId === src.id);
-      if (snapshots.length === 0) continue;
-
-      const availableVersions = snapshots.map(s => s.docVersion || 'latest');
-      const projectVer = dep.resolvedVersion || dep.requestedVersion;
-      const resolution = resolveDocVersion(projectVer, availableVersions, dep.name);
-
-      const chosenSnapshot = snapshots.find(
-        s => (s.docVersion || 'latest') === resolution.selectedDocVersion
-      ) || snapshots[0];
-
-      matches.push({
-        dependency: dep,
-        targetVersion: resolution.selectedDocVersion,
-        confidence: resolution.confidence,
-        snapshotId: chosenSnapshot?.id,
-        matchedBy: resolution.matchType,
-      });
-    }
-
-    return { matches };
-  }
-
-  resolveVersion(projectVersion: string, availableDocVersions: string[], packageName?: string): VersionResolutionResult {
-    return resolveDocVersion(projectVersion, availableDocVersions, packageName);
-  }
-}
-

package/packages/workspace/src/semver.ts

@@ -1,259 +0,0 @@
-import type {
-  DocVersionMatch,
-  VersionResolutionResult,
-} from '../../shared/src/index.ts';
-
-export interface ParsedSemVer {
-  major: number;
-  minor: number;
-  patch: number;
-  prerelease?: string;
-  raw: string;
-}
-
-/**
- * Parses a version string into semantic components.
- * Handles standard SemVer, leading 'v', partial versions ('14', '14.2'),
- * and prereleases ('15.0.0-rc.1', '14.2.0-canary').
- */
-export function parseSemVer(versionStr: string): ParsedSemVer | null {
-  if (!versionStr || typeof versionStr !== 'string') return null;
-
-  const cleaned = versionStr.trim().replace(/^[v=]/, '');
-  // Match major, optional minor, optional patch, optional prerelease
-  const match = cleaned.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?/);
-  if (!match) return null;
-
-  const major = parseInt(match[1], 10);
-  const minor = match[2] !== undefined ? parseInt(match[2], 10) : 0;
-  const patch = match[3] !== undefined ? parseInt(match[3], 10) : 0;
-  const prerelease = match[4];
-
-  return { major, minor, patch, prerelease, raw: versionStr.trim() };
-}
-
-/**
- * Deterministic SemVer comparison.
- * Returns negative if v1 < v2, positive if v1 > v2, 0 if v1 == v2.
- * Prereleases have lower precedence than normal releases (e.g. 15.0.0-rc.1 < 15.0.0).
- */
-export function compareVersions(v1: string, v2: string): number {
-  const p1 = parseSemVer(v1);
-  const p2 = parseSemVer(v2);
-
-  if (!p1 && !p2) return v1.localeCompare(v2);
-  if (!p1) return -1;
-  if (!p2) return 1;
-
-  if (p1.major !== p2.major) return p1.major - p2.major;
-  if (p1.minor !== p2.minor) return p1.minor - p2.minor;
-  if (p1.patch !== p2.patch) return p1.patch - p2.patch;
-
-  // Prerelease comparison:
-  // 1.0.0-alpha < 1.0.0 (version with prerelease is lower than version without)
-  if (p1.prerelease && !p2.prerelease) return -1;
-  if (!p1.prerelease && p2.prerelease) return 1;
-  if (p1.prerelease && p2.prerelease) {
-    return p1.prerelease.localeCompare(p2.prerelease);
-  }
-
-  return 0;
-}
-
-/**
- * Evaluates whether a concrete version satisfies a SemVer range specification.
- * Supports '^', '~', '>=', '<=', '<', '>', '*', 'x', space-separated and '||'.
- */
-export function satisfiesRange(version: string, range: string): boolean {
-  if (!range || range === '*' || range === 'latest' || range === 'x') {
-    return true;
-  }
-
-  const ver = parseSemVer(version);
-  if (!ver) return false;
-
-  // Handle disjunction (||)
-  if (range.includes('||')) {
-    return range.split('||').some(r => satisfiesRange(version, r.trim()));
-  }
-
-  // Handle conjunction (space separated conditions e.g. ">=14.0.0 <15.0.0")
-  const clauses = range.trim().split(/\s+/).filter(Boolean);
-  if (clauses.length > 1) {
-    return clauses.every(c => satisfiesRange(version, c));
-  }
-
-  const single = clauses[0];
-
-  // Caret ranges: ^14.2.0 -> >=14.2.0 <15.0.0 (or for 0.x: ^0.2.3 -> >=0.2.3 <0.3.0)
-  if (single.startsWith('^')) {
-    const base = parseSemVer(single.slice(1));
-    if (!base) return false;
-    if (ver.major !== base.major) return false;
-    if (base.major === 0) {
-      if (ver.minor !== base.minor) return false;
-      return ver.patch >= base.patch;
-    }
-    if (ver.minor < base.minor) return false;
-    if (ver.minor === base.minor && ver.patch < base.patch) return false;
-    return true;
-  }
-
-  // Tilde ranges: ~14.2.0 -> >=14.2.0 <14.3.0
-  if (single.startsWith('~')) {
-    const base = parseSemVer(single.slice(1));
-    if (!base) return false;
-    if (ver.major !== base.major || ver.minor !== base.minor) return false;
-    return ver.patch >= base.patch;
-  }
-
-  // Wildcard ranges: 14.x or 14.*
-  const wildcardMatch = single.match(/^(\d+)(?:\.(\d+|\*|x))?(?:\.(\d+|\*|x))?$/);
-  if (wildcardMatch) {
-    const wMajor = parseInt(wildcardMatch[1], 10);
-    const wMinor = wildcardMatch[2];
-    if (ver.major !== wMajor) return false;
-    if (wMinor && wMinor !== '*' && wMinor !== 'x') {
-      if (ver.minor !== parseInt(wMinor, 10)) return false;
-    }
-    return true;
-  }
-
-  // Comparison operators: >=, <=, >, <, =
-  const compMatch = single.match(/^(>=|<=|>|<|=)(.+)$/);
-  if (compMatch) {
-    const op = compMatch[1];
-    const target = compMatch[2].trim();
-    const cmp = compareVersions(version, target);
-    if (op === '>=') return cmp >= 0;
-    if (op === '<=') return cmp <= 0;
-    if (op === '>') return cmp > 0;
-    if (op === '<') return cmp < 0;
-    if (op === '=') return cmp === 0;
-  }
-
-  // Direct equality check
-  const targetVer = parseSemVer(single);
-  if (targetVer) {
-    return (
-      ver.major === targetVer.major &&
-      ver.minor === targetVer.minor &&
-      ver.patch === targetVer.patch
-    );
-  }
-
-  return false;
-}
-
-/**
- * Deterministically resolves a project's dependency version to the best available
- * documentation version using the hierarchical confidence ladder:
- * exact (1.0) -> major_minor (0.95) -> major (0.90) -> range (0.85) -> latest_fallback (0.50) -> unresolved (0.0)
- *
- * Never claims exact match when documentation is coarse (e.g. 'v14' or 'latest').
- */
-export function resolveDocVersion(
-  projectVersion: string,
-  availableDocVersions: string[],
-  dependencyName: string = 'package'
-): VersionResolutionResult {
-  if (!availableDocVersions || availableDocVersions.length === 0) {
-    return {
-      dependencyName,
-      projectVersion,
-      selectedDocVersion: 'unresolved',
-      matchType: 'unresolved',
-      confidence: 0.0,
-      availableVersions: [],
-    };
-  }
-
-  const cleaned = projectVersion.replace(/^[\^~=v><\s]+/, '');
-  const pVer = parseSemVer(projectVersion) || parseSemVer(cleaned);
-  const cleanTarget = projectVersion.replace(/^[v=]/, '');
-
-  // 1. Exact match (e.g. project '14.2.3' and doc '14.2.3' or 'v14.2.3')
-  const exactMatch = availableDocVersions.find(v => {
-    const c = v.replace(/^[v=]/, '');
-    return c === cleanTarget;
-  });
-  if (exactMatch) {
-    return {
-      dependencyName,
-      projectVersion,
-      selectedDocVersion: exactMatch,
-      matchType: 'exact',
-      confidence: 1.0,
-      availableVersions: availableDocVersions,
-    };
-  }
-
-  if (pVer) {
-    // 2. Major.Minor match (e.g. project '14.2.3' and doc 'v14.2' or '14.2')
-    const mmTarget = `${pVer.major}.${pVer.minor}`;
-    const mmMatch = availableDocVersions.find(v => {
-      const c = v.replace(/^[v=]/, '');
-      return c === mmTarget || c === `${mmTarget}.x`;
-    });
-    if (mmMatch) {
-      return {
-        dependencyName,
-        projectVersion,
-        selectedDocVersion: mmMatch,
-        matchType: 'major_minor',
-        confidence: 0.95,
-        availableVersions: availableDocVersions,
-      };
-    }
-
-    // 3. Major match (e.g. project '14.2.3' and doc 'v14', '14.x', or '14')
-    const majorTarget = `${pVer.major}`;
-    const majorMatch = availableDocVersions.find(v => {
-      const c = v.replace(/^[v=]/, '');
-      return c === majorTarget || c === `${majorTarget}.x` || c === `${majorTarget}.*`;
-    });
-    if (majorMatch) {
-      return {
-        dependencyName,
-        projectVersion,
-        selectedDocVersion: majorMatch,
-        matchType: 'major',
-        confidence: 0.90,
-        availableVersions: availableDocVersions,
-      };
-    }
-
-    // 4. SemVer range satisfaction (find doc version that satisfies project version range or vice versa)
-    const rangeMatch = availableDocVersions
-      .filter(v => !['latest', 'stable', 'current', 'main', 'default'].includes(v.toLowerCase()))
-      .find(v => {
-        return satisfiesRange(projectVersion, v) || satisfiesRange(v, projectVersion);
-      });
-    if (rangeMatch) {
-      return {
-        dependencyName,
-        projectVersion,
-        selectedDocVersion: rangeMatch,
-        matchType: 'range',
-        confidence: 0.85,
-        availableVersions: availableDocVersions,
-      };
-    }
-  }
-
-  // 5. Fallback: 'latest' / 'stable' / 'current' or highest available version
-  const latestCandidate = availableDocVersions.find(v =>
-    ['latest', 'stable', 'current', 'main', 'default'].includes(v.toLowerCase())
-  );
-
-  const fallbackVersion = latestCandidate || availableDocVersions[0];
-
-  return {
-    dependencyName,
-    projectVersion,
-    selectedDocVersion: fallbackVersion,
-    matchType: 'latest_fallback',
-    confidence: 0.50,
-    availableVersions: availableDocVersions,
-  };
-}