docorbit 0.1.0

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

@@ -0,0 +1,34 @@
+import type { EcosystemStrategy } from './types.ts';
+import { NpmStrategy } from './npm.ts';
+import { CargoStrategy } from './cargo.ts';
+import { GoStrategy } from './go.ts';
+import { PyPiStrategy } from './pypi.ts';
+import { ComposerStrategy } from './composer.ts';
+import { RubyGemsStrategy } from './rubygems.ts';
+import { PubStrategy } from './pub.ts';
+import { MavenStrategy } from './maven.ts';
+
+export type { EcosystemStrategy } from './types.ts';
+export {
+  NpmStrategy,
+  CargoStrategy,
+  GoStrategy,
+  PyPiStrategy,
+  ComposerStrategy,
+  RubyGemsStrategy,
+  PubStrategy,
+  MavenStrategy,
+};
+
+export function getDefaultStrategies(): EcosystemStrategy[] {
+  return [
+    new NpmStrategy(),
+    new CargoStrategy(),
+    new GoStrategy(),
+    new PyPiStrategy(),
+    new ComposerStrategy(),
+    new RubyGemsStrategy(),
+    new PubStrategy(),
+    new MavenStrategy(),
+  ];
+}

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

@@ -0,0 +1,34 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class MavenStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'maven';
+  readonly manifestNames = ['pom.xml'];
+
+  parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    const depRegex = /<dependency>([\s\S]*?)<\/dependency>/g;
+    let match: RegExpExecArray | null;
+
+    while ((match = depRegex.exec(content)) !== null) {
+      const block = match[1];
+      const groupMatch = block.match(/<groupId>([^<]+)<\/groupId>/);
+      const artifactMatch = block.match(/<artifactId>([^<]+)<\/artifactId>/);
+      const verMatch = block.match(/<version>([^<]+)<\/version>/);
+
+      if (artifactMatch) {
+        const name = groupMatch ? `${groupMatch[1]}:${artifactMatch[1]}` : artifactMatch[1];
+        deps.push({
+          name,
+          ecosystem: 'maven',
+          requestedVersion: verMatch ? verMatch[1].trim() : '*',
+          resolvedVersion: verMatch ? verMatch[1].trim() : undefined,
+          sourceFile: relPath,
+          packagePath: packageDir,
+          isDev: block.includes('<scope>test</scope>'),
+        });
+      }
+    }
+    return deps;
+  }
+}

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

@@ -0,0 +1,83 @@
+import { join } from 'node:path';
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class NpmStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'npm';
+  readonly manifestNames = ['package.json'];
+  readonly lockfileNames = ['package-lock.json'];
+
+  parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    try {
+      const pkg = JSON.parse(content);
+
+      const addSection = (section: Record<string, string> | undefined, isDev: boolean) => {
+        if (!section) return;
+        for (const [name, version] of Object.entries(section)) {
+          deps.push({
+            name,
+            ecosystem: 'npm',
+            requestedVersion: String(version),
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev,
+          });
+        }
+      };
+
+      addSection(pkg.dependencies, false);
+      addSection(pkg.devDependencies, true);
+      addSection(pkg.peerDependencies, false);
+    } catch {
+      // Malformed JSON
+    }
+    return deps;
+  }
+
+  parseLockfile(_fileName: string, content: string): Map<string, string> {
+    const resolved = new Map<string, string>();
+    try {
+      const lock = JSON.parse(content);
+      // npm v2/v3 lockfile format
+      if (lock.packages && typeof lock.packages === 'object') {
+        for (const [key, val] of Object.entries(lock.packages)) {
+          if (val && typeof val === 'object' && (val as any).version) {
+            const pkgName = key.replace(/^node_modules\//, '');
+            if (pkgName && !pkgName.includes('node_modules')) {
+              resolved.set(pkgName, String((val as any).version));
+            }
+          }
+        }
+      }
+      // npm v1 lockfile format fallback
+      if (lock.dependencies && typeof lock.dependencies === 'object') {
+        for (const [name, val] of Object.entries(lock.dependencies)) {
+          if (val && typeof val === 'object' && (val as any).version) {
+            resolved.set(name, String((val as any).version));
+          }
+        }
+      }
+    } catch {
+      // Malformed lockfile
+    }
+    return resolved;
+  }
+
+  resolveVersions(
+    deps: ProjectDependency[],
+    pkgDir: string,
+    lockfileCache: Map<string, Map<string, string>>
+  ): void {
+    const lockMap =
+      lockfileCache.get('package-lock.json') ||
+      lockfileCache.get(join(pkgDir, 'package-lock.json'));
+
+    if (lockMap) {
+      for (const dep of deps) {
+        const resolved = lockMap.get(dep.name);
+        if (resolved) dep.resolvedVersion = resolved;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,40 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class PubStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'pub';
+  readonly manifestNames = ['pubspec.yaml'];
+
+  parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    const lines = content.split('\n');
+    let inDependencies = false;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed === 'dependencies:' || trimmed === 'dev_dependencies:') {
+        inDependencies = true;
+        continue;
+      }
+      if (inDependencies && /^[a-zA-Z0-9_]+:/.test(line) && !line.startsWith(' ')) {
+        inDependencies = false;
+        continue;
+      }
+
+      if (inDependencies && trimmed && !trimmed.startsWith('#')) {
+        const match = trimmed.match(/^([a-zA-Z0-9_]+)\s*:\s*(.+)$/);
+        if (match && match[1] !== 'sdk' && match[1] !== 'flutter') {
+          deps.push({
+            name: match[1],
+            ecosystem: 'pub',
+            requestedVersion: match[2]?.trim() || '*',
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev: false,
+          });
+        }
+      }
+    }
+    return deps;
+  }
+}

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

@@ -0,0 +1,100 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class PyPiStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'pypi';
+  readonly manifestNames = ['requirements.txt', 'pyproject.toml'];
+
+  parseManifest(fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const lower = fileName.toLowerCase();
+    if (lower === 'requirements.txt') {
+      return this.parseRequirementsTxt(content, relPath, packageDir);
+    }
+    if (lower === 'pyproject.toml') {
+      return this.parsePyprojectToml(content, relPath, packageDir);
+    }
+    return [];
+  }
+
+  private parseRequirementsTxt(content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('-')) continue;
+
+      // Match name and version specifier (e.g. requests==2.31.0, flask>=3.0.0, numpy)
+      const match = trimmed.match(/^([a-zA-Z0-9_.-]+)\s*([=><~^!].*)?$/);
+      if (match) {
+        const name = match[1];
+        const spec = match[2]?.trim() || '*';
+        const exactMatch = spec.match(/^==\s*([a-zA-Z0-9_.-]+)$/);
+        deps.push({
+          name,
+          ecosystem: 'pypi',
+          requestedVersion: spec,
+          resolvedVersion: exactMatch ? exactMatch[1] : undefined,
+          sourceFile: relPath,
+          packagePath: packageDir,
+          isDev: false,
+        });
+      }
+    }
+    return deps;
+  }
+
+  private parsePyprojectToml(content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    const lines = content.split('\n');
+    let inDependencies = false;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        const sec = trimmed.slice(1, -1).trim();
+        inDependencies =
+          sec === 'project.dependencies' ||
+          sec === 'tool.poetry.dependencies' ||
+          sec === 'project.optional-dependencies';
+        continue;
+      }
+
+      if (inDependencies && trimmed && !trimmed.startsWith('#')) {
+        // Poetry format: name = "^1.2.3" or name = { version = "1.2.3" }
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx !== -1) {
+          const name = trimmed.slice(0, eqIdx).trim();
+          if (name.toLowerCase() === 'python') continue;
+          const val = trimmed.slice(eqIdx + 1).trim();
+          let ver = '*';
+          const vMatch = val.match(/"([^"]+)"/);
+          if (vMatch) ver = vMatch[1];
+          deps.push({
+            name,
+            ecosystem: 'pypi',
+            requestedVersion: ver,
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev: false,
+          });
+        } else if (trimmed.startsWith('"') || trimmed.startsWith("'")) {
+          // Standard PEP 621: "requests>=2.28.0",
+          const clean = trimmed.replace(/^[",']|[",']$/g, '');
+          const match = clean.match(/^([a-zA-Z0-9_.-]+)\s*([=><~^!].*)?$/);
+          if (match) {
+            deps.push({
+              name: match[1],
+              ecosystem: 'pypi',
+              requestedVersion: match[2]?.trim() || '*',
+              sourceFile: relPath,
+              packagePath: packageDir,
+              isDev: false,
+            });
+          }
+        }
+      }
+    }
+    return deps;
+  }
+}

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

@@ -0,0 +1,30 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+
+export class RubyGemsStrategy implements EcosystemStrategy {
+  readonly ecosystem = 'rubygems';
+  readonly manifestNames = ['gemfile'];
+
+  parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[] {
+    const deps: ProjectDependency[] = [];
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('gem ') || trimmed.startsWith("gem\t")) {
+        const match = trimmed.match(/^gem\s+['"]([^'"]+)['"](?:\s*,\s*['"]([^'"]+)['"])?/);
+        if (match) {
+          deps.push({
+            name: match[1],
+            ecosystem: 'rubygems',
+            requestedVersion: match[2] || '*',
+            sourceFile: relPath,
+            packagePath: packageDir,
+            isDev: false,
+          });
+        }
+      }
+    }
+    return deps;
+  }
+}

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

@@ -0,0 +1,18 @@
+import type {
+  Ecosystem,
+  ProjectDependency,
+} from '../../../shared/src/index.ts';
+
+export interface EcosystemStrategy {
+  readonly ecosystem: Ecosystem;
+  readonly manifestNames: string[];
+  readonly lockfileNames?: string[];
+
+  parseManifest(fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[];
+  parseLockfile?(fileName: string, content: string): Map<string, string>;
+  resolveVersions?(
+    deps: ProjectDependency[],
+    pkgDir: string,
+    lockfileCache: Map<string, Map<string, string>>
+  ): void;
+}

package/packages/workspace/src/index.ts

@@ -0,0 +1,5 @@
+export * from './semver.ts';
+export * from './detector.ts';
+export * from './lockfile.ts';
+export * from './resolver.ts';
+export * from './ecosystems/index.ts';

package/packages/workspace/src/lockfile.ts

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