docorbit 0.1.0 → 0.1.2

package/dist/packages/workspace/src/ecosystems/index.js

@@ -0,0 +1,21 @@
+import { NpmStrategy } from "./npm.js";
+import { CargoStrategy } from "./cargo.js";
+import { GoStrategy } from "./go.js";
+import { PyPiStrategy } from "./pypi.js";
+import { ComposerStrategy } from "./composer.js";
+import { RubyGemsStrategy } from "./rubygems.js";
+import { PubStrategy } from "./pub.js";
+import { MavenStrategy } from "./maven.js";
+export { NpmStrategy, CargoStrategy, GoStrategy, PyPiStrategy, ComposerStrategy, RubyGemsStrategy, PubStrategy, MavenStrategy, };
+export function getDefaultStrategies() {
+    return [
+        new NpmStrategy(),
+        new CargoStrategy(),
+        new GoStrategy(),
+        new PyPiStrategy(),
+        new ComposerStrategy(),
+        new RubyGemsStrategy(),
+        new PubStrategy(),
+        new MavenStrategy(),
+    ];
+}

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

@@ -0,0 +1,7 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+export declare class MavenStrategy implements EcosystemStrategy {
+    readonly ecosystem = "maven";
+    readonly manifestNames: string[];
+    parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[];
+}

package/dist/packages/workspace/src/ecosystems/maven.js

@@ -0,0 +1,28 @@
+export class MavenStrategy {
+    ecosystem = 'maven';
+    manifestNames = ['pom.xml'];
+    parseManifest(_fileName, content, relPath, packageDir) {
+        const deps = [];
+        const depRegex = /<dependency>([\s\S]*?)<\/dependency>/g;
+        let match;
+        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/dist/packages/workspace/src/ecosystems/npm.d.ts

@@ -0,0 +1,10 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+export declare class NpmStrategy implements EcosystemStrategy {
+    readonly ecosystem = "npm";
+    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/dist/packages/workspace/src/ecosystems/npm.js

@@ -0,0 +1,73 @@
+import { join } from 'node:path';
+export class NpmStrategy {
+    ecosystem = 'npm';
+    manifestNames = ['package.json'];
+    lockfileNames = ['package-lock.json'];
+    parseManifest(_fileName, content, relPath, packageDir) {
+        const deps = [];
+        try {
+            const pkg = JSON.parse(content);
+            const addSection = (section, isDev) => {
+                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, content) {
+        const resolved = new Map();
+        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.version) {
+                        const pkgName = key.replace(/^node_modules\//, '');
+                        if (pkgName && !pkgName.includes('node_modules')) {
+                            resolved.set(pkgName, String(val.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.version) {
+                        resolved.set(name, String(val.version));
+                    }
+                }
+            }
+        }
+        catch {
+            // Malformed lockfile
+        }
+        return resolved;
+    }
+    resolveVersions(deps, pkgDir, lockfileCache) {
+        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/dist/packages/workspace/src/ecosystems/pub.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+export declare class PubStrategy implements EcosystemStrategy {
+    readonly ecosystem = "pub";
+    readonly manifestNames: string[];
+    parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[];
+}

package/dist/packages/workspace/src/ecosystems/pub.js

@@ -0,0 +1,34 @@
+export class PubStrategy {
+    ecosystem = 'pub';
+    manifestNames = ['pubspec.yaml'];
+    parseManifest(_fileName, content, relPath, packageDir) {
+        const deps = [];
+        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/dist/packages/workspace/src/ecosystems/pypi.d.ts

@@ -0,0 +1,9 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+export declare class PyPiStrategy implements EcosystemStrategy {
+    readonly ecosystem = "pypi";
+    readonly manifestNames: string[];
+    parseManifest(fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[];
+    private parseRequirementsTxt;
+    private parsePyprojectToml;
+}

package/dist/packages/workspace/src/ecosystems/pypi.js

@@ -0,0 +1,94 @@
+export class PyPiStrategy {
+    ecosystem = 'pypi';
+    manifestNames = ['requirements.txt', 'pyproject.toml'];
+    parseManifest(fileName, content, relPath, packageDir) {
+        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 [];
+    }
+    parseRequirementsTxt(content, relPath, packageDir) {
+        const deps = [];
+        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;
+    }
+    parsePyprojectToml(content, relPath, packageDir) {
+        const deps = [];
+        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/dist/packages/workspace/src/ecosystems/rubygems.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectDependency } from '../../../shared/src/index.ts';
+import type { EcosystemStrategy } from './types.ts';
+export declare class RubyGemsStrategy implements EcosystemStrategy {
+    readonly ecosystem = "rubygems";
+    readonly manifestNames: string[];
+    parseManifest(_fileName: string, content: string, relPath: string, packageDir: string): ProjectDependency[];
+}

package/dist/packages/workspace/src/ecosystems/rubygems.js

@@ -0,0 +1,25 @@
+export class RubyGemsStrategy {
+    ecosystem = 'rubygems';
+    manifestNames = ['gemfile'];
+    parseManifest(_fileName, content, relPath, packageDir) {
+        const deps = [];
+        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/dist/packages/workspace/src/ecosystems/types.d.ts

@@ -0,0 +1,9 @@
+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/dist/packages/workspace/src/ecosystems/types.js

@@ -0,0 +1 @@
+export {};

package/dist/packages/workspace/src/index.js

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

package/dist/packages/workspace/src/lockfile.d.ts

@@ -0,0 +1,21 @@
+import type { DocsLock, WorkspaceScanResult } from '../../shared/src/index.ts';
+import type { DocOrbitRepository } from '../../storage/src/index.ts';
+export declare const DOCS_LOCK_FILENAME = "docs.lock";
+/**
+ * Reads and parses docs.lock from a project directory if present.
+ */
+export declare function readDocsLock(projectDir: string): DocsLock | null;
+/**
+ * Deterministically writes a docs.lock file to project directory.
+ * Sorts dependency keys alphabetically and uses 2-space indentation.
+ */
+export declare function writeDocsLock(projectDir: string, lock: DocsLock): void;
+/**
+ * Generates a DocsLock manifest from workspace scan result and repository state.
+ * Preserves timestamps for unchanged documentation snapshots to prevent lockfile churn.
+ */
+export declare function generateDocsLock(scanResult: WorkspaceScanResult, repo: DocOrbitRepository, existingLock?: DocsLock | null): DocsLock;
+/**
+ * Selectively or globally updates docs.lock for a project.
+ */
+export declare function updateDocsLock(scanResult: WorkspaceScanResult, repo: DocOrbitRepository, existingLock: DocsLock, specificDependency?: string): DocsLock;

package/dist/packages/workspace/src/lockfile.js

@@ -0,0 +1,153 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveDocVersion } from "./semver.js";
+export const DOCS_LOCK_FILENAME = 'docs.lock';
+/**
+ * Reads and parses docs.lock from a project directory if present.
+ */
+export function readDocsLock(projectDir) {
+    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;
+        }
+    }
+    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, lock) {
+    const filePath = join(projectDir, DOCS_LOCK_FILENAME);
+    // Sort dependency keys alphabetically
+    const sortedDeps = {};
+    for (const key of Object.keys(lock.dependencies).sort()) {
+        sortedDeps[key] = lock.dependencies[key];
+    }
+    const deterministicLock = {
+        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, repo) {
+    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, repo, existingLock) {
+    const lockedDeps = {};
+    const allSnapshots = repo.listSnapshots();
+    // Detect duplicate package names across monorepo packages
+    const nameCounts = new Map();
+    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();
+        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, repo, existingLock, specificDependency) {
+    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/dist/packages/workspace/src/resolver.d.ts

@@ -0,0 +1,39 @@
+import type { DocsLock, ProjectDependency, WorkspaceScanResult, VersionResolutionResult } from '../../shared/src/index.ts';
+import type { DocOrbitRepository } from '../../storage/src/index.ts';
+export interface ResolvedProjectContext {
+    projectDir: string;
+    hasLockfile: boolean;
+    matchedDependency?: {
+        name: string;
+        projectVersion: string;
+        targetDocVersion: string;
+        targetSnapshotId?: string;
+        confidence: number;
+        matchType: string;
+    };
+    allDependencies: ProjectDependency[];
+}
+/**
+ * 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 declare function resolveProjectContext(projectDir: string, query: string, repo: DocOrbitRepository): ResolvedProjectContext;
+export interface WorkspaceMatch {
+    dependency: ProjectDependency;
+    targetVersion: string;
+    confidence: number;
+    snapshotId?: string;
+    matchedBy: string;
+}
+export interface WorkspaceResolutionSummary {
+    matches: WorkspaceMatch[];
+}
+export declare class WorkspaceResolver {
+    private repo;
+    constructor(repo: DocOrbitRepository);
+    resolveProjectContext(projectDir: string, query: string): ResolvedProjectContext;
+    scanWorkspace(projectDir: string): WorkspaceScanResult;
+    resolveWorkspace(scan: WorkspaceScanResult, _existingLock?: DocsLock | null): WorkspaceResolutionSummary;
+    resolveVersion(projectVersion: string, availableDocVersions: string[], packageName?: string): VersionResolutionResult;
+}