pax_global_header00006660000000000000000000000064151403747250014522gustar00rootroot0000000000000052 comment=c1bdbb4bb74fe937b0024dd14a2e4eebe03a28f2 opencode-python-docs-0.2.0/000077500000000000000000000000001514037472500155625ustar00rootroot00000000000000opencode-python-docs-0.2.0/.github/000077500000000000000000000000001514037472500171225ustar00rootroot00000000000000opencode-python-docs-0.2.0/.github/workflows/000077500000000000000000000000001514037472500211575ustar00rootroot00000000000000opencode-python-docs-0.2.0/.github/workflows/ci.yml000066400000000000000000000007761514037472500223070ustar00rootroot00000000000000name: CI on: push: branches: [main] pull_request: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v2 with: bun-version: latest - name: Install dependencies run: bun install - name: Type check run: bun run typecheck - name: Lint run: bun run lint - name: Check format run: bun run check - name: Test run: bun test opencode-python-docs-0.2.0/.github/workflows/release.yml000066400000000000000000000012711514037472500233230ustar00rootroot00000000000000name: Release on: push: tags: - 'v*' workflow_dispatch: jobs: publish: runs-on: ubuntu-latest permissions: contents: read id-token: write steps: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v2 with: bun-version: latest - uses: actions/setup-node@v4 with: node-version: 'lts/*' registry-url: 'https://registry.npmjs.org' - name: Update npm run: npm install -g npm@latest - name: Install dependencies run: bun install - name: Build run: bun run build - name: Publish to npm run: npm publish --provenance --access public opencode-python-docs-0.2.0/.gitignore000066400000000000000000000002621514037472500175520ustar00rootroot00000000000000# Dependencies node_modules/ # Build output dist/ # Lock files (use bun.lock instead) package-lock.json yarn.lock # OS files .DS_Store # IDE .idea/ .vscode/ # Cache .cache/ opencode-python-docs-0.2.0/.gitmessage000066400000000000000000000023411514037472500177130ustar00rootroot00000000000000# Commit Message Template # # Format: (): # # Types: # feat - New feature # fix - Bug fix # docs - Documentation changes # style - Formatting, missing semicolons, etc # refactor - Code refactoring # perf - Performance improvements # test - Adding or updating tests # chore - Build process, dependencies, etc # # Scope: optional, describes area of change (e.g., fetch_python_doc) # # Subject: brief description (imperative mood, no period) # Body (separated by blank line): # - Explain WHAT and WHY (not HOW) # - Wrap at 72 characters # - Use bullet points for multiple changes # Footer (optional): # - Reference issues: Closes #123, Fixes #456 # - Breaking changes: BREAKING CHANGE: description # Example: # feat(fetch_python_doc): add offset/limit pagination # # Add offset and limit parameters to enable windowing of large # documentation responses. This allows agents to lazy load content # in chunks while respecting context caps. # # - Add offset parameter (default: 0) for character offset # - Add limit parameter (default: 12000) for max characters # - Update formatDocument() to window content with progress indicators # - Document lazy loading usage patterns in README opencode-python-docs-0.2.0/LICENSE000066400000000000000000000020551514037472500165710ustar00rootroot00000000000000MIT License Copyright (c) 2026 Yago Riveiro Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. opencode-python-docs-0.2.0/README.md000066400000000000000000000045121514037472500170430ustar00rootroot00000000000000# opencode-python-docs OpenCode plugin for Python documentation lookup via DevDocs. ## Quick Start Add to `~/.config/opencode/opencode.json`: ```json { "plugin": ["opencode-python-docs"] } ``` ## Features - **Search** Python stdlib, language reference, tutorials, and more - **Fetch** full documentation as clean Markdown - **Cache** with intelligent TTL-based garbage collection - **Multiple versions** supported: 3.14, 3.13, 3.12, 3.11, 3.10, 3.9 ## Tools ### `python_docs` Search Python documentation index. | Argument | Type | Description | | ---------- | ------ | ------------- | | `query` | string | Search query (e.g., 'asyncio', 'pathlib') | | `version` | string? | Python version (default: 3.14) | | `type` | string? | Filter by doc type | | `limit` | number? | Max results (default: 20) | **Example:** ```text python_docs query="asyncio" version="3.12" ``` ### `fetch_python_doc` Fetch full documentation as Markdown. | Argument | Type | Description | | ---------- | ------ | ------------- | | `path` | string | Doc path from search results | | `version` | string? | Python version (default: 3.14) | | `anchor` | string? | Jump to specific section by anchor ID | | `offset` | number? | Character offset for pagination (default: 0) | | `limit` | number? | Max characters to return (default: 12000) | **Example:** ```text fetch_python_doc path="library/asyncio" ``` **Pagination example:** ```text # First chunk fetch_python_doc path="library/asyncio" offset=0 limit=5000 # Continue reading fetch_python_doc path="library/asyncio" offset=5000 limit=5000 ``` ## Caching - **Index cache**: 24 hours TTL - **Doc cache**: 7 days TTL - **Location**: `~/.cache/opencode/python-docs/` - **Garbage collection**: Runs on startup and server reconnect - **Schema-aware invalidation**: Cached docs missing required fields (e.g., anchor index) are refetched even within TTL ## Development ```bash git clone https://github.com/yriveiro/opencode-python-docs cd opencode-python-docs bun install bun run build ``` ### Scripts | Command | Description | | --------- | ------------- | | `bun run build` | Build the plugin | | `bun run typecheck` | Run TypeScript type checking | | `bun run test` | Run tests | | `bun run format` | Format code with Biome | | `bun run lint` | Run Biome linter | | `bun run check` | Run all checks (lint + format) | ## License MIT opencode-python-docs-0.2.0/biome.json000066400000000000000000000013521514037472500175510ustar00rootroot00000000000000{ "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true }, "files": { "ignoreUnknown": false, "includes": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx", "**/*.json"] }, "formatter": { "enabled": true, "indentStyle": "space", "lineWidth": 100 }, "linter": { "enabled": true, "rules": { "recommended": true, "suspicious": { "noExplicitAny": "off" } } }, "javascript": { "formatter": { "quoteStyle": "double" } }, "assist": { "enabled": true, "actions": { "source": { "organizeImports": { "level": "on" } } } } } opencode-python-docs-0.2.0/bun.lock000066400000000000000000000110511514037472500172160ustar00rootroot00000000000000{ "lockfileVersion": 1, "configVersion": 1, "workspaces": { "": { "name": "opencode-python-docs", "dependencies": { "turndown": "^7.2.2", "turndown-plugin-gfm": "^1.0.2", }, "devDependencies": { "@biomejs/biome": "^2.3.13", "@types/turndown": "^5.0.6", "bun-types": "^1.3.8", "typescript": "^5.9.3", }, "peerDependencies": { "@opencode-ai/plugin": ">=1.0.0", }, }, }, "packages": { "@biomejs/biome": ["@biomejs/biome@2.3.13", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.3.13", "@biomejs/cli-darwin-x64": "2.3.13", "@biomejs/cli-linux-arm64": "2.3.13", "@biomejs/cli-linux-arm64-musl": "2.3.13", "@biomejs/cli-linux-x64": "2.3.13", "@biomejs/cli-linux-x64-musl": "2.3.13", "@biomejs/cli-win32-arm64": "2.3.13", "@biomejs/cli-win32-x64": "2.3.13" }, "bin": { "biome": "bin/biome" } }, "sha512-Fw7UsV0UAtWIBIm0M7g5CRerpu1eKyKAXIazzxhbXYUyMkwNrkX/KLkGI7b+uVDQ5cLUMfOC9vR60q9IDYDstA=="], "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.3.13", "", { "os": "darwin", "cpu": "arm64" }, "sha512-0OCwP0/BoKzyJHnFdaTk/i7hIP9JHH9oJJq6hrSCPmJPo8JWcJhprK4gQlhFzrwdTBAW4Bjt/RmCf3ZZe59gwQ=="], "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.3.13", "", { "os": "darwin", "cpu": "x64" }, "sha512-AGr8OoemT/ejynbIu56qeil2+F2WLkIjn2d8jGK1JkchxnMUhYOfnqc9sVzcRxpG9Ycvw4weQ5sprRvtb7Yhcw=="], "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.3.13", "", { "os": "linux", "cpu": "arm64" }, "sha512-xvOiFkrDNu607MPMBUQ6huHmBG1PZLOrqhtK6pXJW3GjfVqJg0Z/qpTdhXfcqWdSZHcT+Nct2fOgewZvytESkw=="], "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.3.13", "", { "os": "linux", "cpu": "arm64" }, "sha512-TUdDCSY+Eo/EHjhJz7P2GnWwfqet+lFxBZzGHldrvULr59AgahamLs/N85SC4+bdF86EhqDuuw9rYLvLFWWlXA=="], "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.3.13", "", { "os": "linux", "cpu": "x64" }, "sha512-s+YsZlgiXNq8XkgHs6xdvKDFOj/bwTEevqEY6rC2I3cBHbxXYU1LOZstH3Ffw9hE5tE1sqT7U23C00MzkXztMw=="], "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.3.13", "", { "os": "linux", "cpu": "x64" }, "sha512-0bdwFVSbbM//Sds6OjtnmQGp4eUjOTt6kHvR/1P0ieR9GcTUAlPNvPC3DiavTqq302W34Ae2T6u5VVNGuQtGlQ=="], "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.3.13", "", { "os": "win32", "cpu": "arm64" }, "sha512-QweDxY89fq0VvrxME+wS/BXKmqMrOTZlN9SqQ79kQSIc3FrEwvW/PvUegQF6XIVaekncDykB5dzPqjbwSKs9DA=="], "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.3.13", "", { "os": "win32", "cpu": "x64" }, "sha512-trDw2ogdM2lyav9WFQsdsfdVy1dvZALymRpgmWsvSez0BJzBjulhOT/t+wyKeh3pZWvwP3VMs1SoOKwO3wecMQ=="], "@mixmark-io/domino": ["@mixmark-io/domino@2.2.0", "", {}, "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw=="], "@opencode-ai/plugin": ["@opencode-ai/plugin@1.1.48", "", { "dependencies": { "@opencode-ai/sdk": "1.1.48", "zod": "4.1.8" } }, "sha512-KkaSMevXmz7tOwYDMJeWiXE5N8LmRP18qWI5Xhv3+c+FdGPL+l1hQrjSgyv3k7Co7qpCyW3kAUESBB7BzIOl2w=="], "@opencode-ai/sdk": ["@opencode-ai/sdk@1.1.48", "", {}, "sha512-j5/79X45fUPWVD2Ffm/qvwLclDCdPeV+TYMDrm9to0p4pmzhmeKevCsyiRdLg0o0HE3AFRUnOo2rdO9NetN79A=="], "@types/node": ["@types/node@25.2.0", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-DZ8VwRFUNzuqJ5khrvwMXHmvPe+zGayJhr2CDNiKB1WBE1ST8Djl00D0IC4vvNmHMdj6DlbYRIaFE7WHjlDl5w=="], "@types/turndown": ["@types/turndown@5.0.6", "", {}, "sha512-ru00MoyeeouE5BX4gRL+6m/BsDfbRayOskWqUvh7CLGW+UXxHQItqALa38kKnOiZPqJrtzJUgAC2+F0rL1S4Pg=="], "bun-types": ["bun-types@1.3.8", "", { "dependencies": { "@types/node": "*" } }, "sha512-fL99nxdOWvV4LqjmC+8Q9kW3M4QTtTR1eePs94v5ctGqU8OeceWrSUaRw3JYb7tU3FkMIAjkueehrHPPPGKi5Q=="], "turndown": ["turndown@7.2.2", "", { "dependencies": { "@mixmark-io/domino": "^2.2.0" } }, "sha512-1F7db8BiExOKxjSMU2b7if62D/XOyQyZbPKq/nUwopfgnHlqXHqQ0lvfUTeUIr1lZJzOPFn43dODyMSIfvWRKQ=="], "turndown-plugin-gfm": ["turndown-plugin-gfm@1.0.2", "", {}, "sha512-vwz9tfvF7XN/jE0dGoBei3FXWuvll78ohzCZQuOb+ZjWrs3a0XhQVomJEb2Qh4VHTPNRO4GPZh0V7VRbiWwkRg=="], "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="], "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="], "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="], } } opencode-python-docs-0.2.0/package.json000066400000000000000000000025521514037472500200540ustar00rootroot00000000000000{ "name": "opencode-python-docs", "version": "0.2.0", "description": "OpenCode plugin for Python documentation lookup via DevDocs", "module": "dist/index.js", "main": "dist/index.js", "types": "src/index.ts", "type": "module", "files": [ "src", "dist" ], "scripts": { "build": "bun build src/index.ts --outdir dist --target bun", "clean": "rm -rf dist node_modules bun.lock", "typecheck": "tsc --noEmit", "prepublishOnly": "bun run typecheck && bun run build", "test": "bun test", "test:watch": "bun test --watch", "format": "biome format --write .", "lint": "biome lint .", "check": "biome check ." }, "keywords": [ "opencode", "plugin", "python", "documentation", "devdocs" ], "author": "yriveiro", "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/yriveiro/opencode-python-docs.git" }, "homepage": "https://github.com/yriveiro/opencode-python-docs#readme", "bugs": { "url": "https://github.com/yriveiro/opencode-python-docs/issues" }, "dependencies": { "turndown": "^7.2.2", "turndown-plugin-gfm": "^1.0.2" }, "peerDependencies": { "@opencode-ai/plugin": ">=1.0.0" }, "devDependencies": { "@biomejs/biome": "^2.3.13", "@types/turndown": "^5.0.6", "bun-types": "^1.3.8", "typescript": "^5.9.3" } } opencode-python-docs-0.2.0/src/000077500000000000000000000000001514037472500163515ustar00rootroot00000000000000opencode-python-docs-0.2.0/src/cache.ts000066400000000000000000000066611514037472500177750ustar00rootroot00000000000000import { createHash } from "node:crypto"; import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync, } from "node:fs"; import { dirname, join } from "node:path"; /** Interface for cache operations, enabling dependency injection in tests. */ export interface CacheManagerInterface { getIndexPath(version: string): string; getSearchIndexPath(version: string): string; getDocPath(version: string, docPath: string): string; isValid(path: string, ttlMs: number): boolean; read(path: string): T | null; write(path: string, data: T): void; runGarbageCollection( indexTtlMs: number, docTtlMs: number, ): { scanned: number; deleted: number; errors: number }; } function hash(input: string): string { return createHash("sha1").update(input).digest("hex"); } /** * Creates a file-based cache manager for storing documentation. * Uses SHA-1 hashes for document filenames to handle arbitrary paths. * @param cacheRoot - Root directory for all cached files. * @returns A CacheManagerInterface implementation. */ export function CacheManager(cacheRoot: string): CacheManagerInterface { if (!existsSync(cacheRoot)) { mkdirSync(cacheRoot, { recursive: true }); } return { getIndexPath(version: string): string { return join(cacheRoot, `python-${version}.json`); }, getSearchIndexPath(version: string): string { return join(cacheRoot, `python-${version}-search-index.json`); }, getDocPath(version: string, docPath: string): string { return join(cacheRoot, "docs", version, `${hash(docPath)}.json`); }, isValid(path: string, ttlMs: number): boolean { try { return Date.now() - statSync(path).mtimeMs < ttlMs; } catch { return false; } }, read(path: string): T | null { try { return JSON.parse(readFileSync(path, "utf-8")) as T; } catch { return null; } }, write(path: string, data: T): void { const dir = dirname(path); if (!existsSync(dir)) { mkdirSync(dir, { recursive: true }); } writeFileSync(path, JSON.stringify(data)); }, runGarbageCollection( indexTtlMs: number, docTtlMs: number, ): { scanned: number; deleted: number; errors: number } { let scanned = 0; let deleted = 0; let errors = 0; const tryDelete = (filePath: string, ttl: number) => { scanned++; if (!this.isValid(filePath, ttl)) { try { unlinkSync(filePath); deleted++; } catch { errors++; } } }; if (existsSync(cacheRoot)) { try { for (const file of readdirSync(cacheRoot)) { if (file.endsWith(".json")) { tryDelete(join(cacheRoot, file), indexTtlMs); } } } catch { errors++; } } const docsRoot = join(cacheRoot, "docs"); if (existsSync(docsRoot)) { try { for (const version of readdirSync(docsRoot)) { const versionDir = join(docsRoot, version); try { for (const doc of readdirSync(versionDir)) { tryDelete(join(versionDir, doc), docTtlMs); } } catch { errors++; } } } catch { errors++; } } return { scanned, deleted, errors }; }, }; } opencode-python-docs-0.2.0/src/config.ts000066400000000000000000000014771514037472500201770ustar00rootroot00000000000000import { homedir } from "node:os"; import { join } from "node:path"; /** Root directory for cached documentation files. */ export const CACHE_ROOT = join(homedir(), ".cache", "opencode", "python-docs"); /** Python versions available in DevDocs. */ export const SUPPORTED_VERSIONS = ["3.14", "3.13", "3.12", "3.11", "3.10", "3.9"] as const; /** Union type of supported Python version strings. */ export type PythonVersion = (typeof SUPPORTED_VERSIONS)[number]; /** Default Python version used when not specified. */ export const DEFAULT_VERSION: PythonVersion = "3.14"; /** Plugin configuration constants. */ export const CONFIG = { baseUrl: "https://documents.devdocs.io", indexTtlMs: 24 * 60 * 60 * 1000, docTtlMs: 7 * 24 * 60 * 60 * 1000, fetchTimeoutMs: 30_000, maxWindow: 12_000, defaultLimit: 20, } as const; opencode-python-docs-0.2.0/src/doc-service.ts000066400000000000000000000161531514037472500211320ustar00rootroot00000000000000import type { CacheManagerInterface } from "./cache"; import type { PythonVersion } from "./config"; import { CONFIG } from "./config"; import { htmlToMarkdown } from "./html-to-markdown"; import type { Logger } from "./logger"; import { createSearchIndex, getAvailableTypes, inferTypesForQuery, type SearchIndex, type TypeInferenceResult, } from "./search-index"; import type { CachedDoc, DocIndex, FetchedDoc } from "./types"; async function fetchWithTimeout(url: string, log: Logger): Promise { await log.info(`Fetching: ${url}`); const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), CONFIG.fetchTimeoutMs); try { const res = await fetch(url, { signal: controller.signal }); if (!res.ok) throw new Error(`HTTP ${res.status}`); return await res.text(); } catch (err) { await log.error(`Fetch failed: ${url} → ${err}`); throw err; } finally { clearTimeout(timer); } } /** Service for fetching and searching Python documentation. */ export interface DocService { getIndex(version: PythonVersion): Promise; getSearchIndex(version: PythonVersion): Promise; getDoc(version: PythonVersion, path: string): Promise; search(index: DocIndex, query: string, type?: string, limit?: number): DocIndex["entries"]; searchWithFallback( index: DocIndex, searchIndex: SearchIndex, query: string, type?: string, limit?: number, ): Promise<{ results: DocIndex["entries"]; fallbackUsed: boolean; typeInference?: TypeInferenceResult; }>; suggestTypes(searchIndex: SearchIndex, query: string): TypeInferenceResult; getAvailableTypes(searchIndex: SearchIndex): string[]; } /** * Creates a documentation service with caching and search capabilities. * @param cache - Cache manager for storing fetched documentation. * @param log - Logger for tracking fetch operations. * @returns DocService implementation. */ export function createDocService(cache: CacheManagerInterface, log: Logger): DocService { return { async getIndex(version: PythonVersion): Promise { const indexPath = cache.getIndexPath(version); if (cache.isValid(indexPath, CONFIG.indexTtlMs)) { const cached = cache.read(indexPath); if (cached) return cached; } const text = await fetchWithTimeout(`${CONFIG.baseUrl}/python~${version}/index.json`, log); const index = JSON.parse(text) as DocIndex; cache.write(indexPath, index); return index; }, async getSearchIndex(version: PythonVersion): Promise { const searchIndexPath = cache.getSearchIndexPath(version); // Check if we have a valid cached search index if (cache.isValid(searchIndexPath, CONFIG.indexTtlMs)) { const cached = cache.read(searchIndexPath); if (cached) { await log.info(`Using cached search index for Python ${version}`); return cached; } } // Build search index from the main index await log.info(`Building search index for Python ${version}...`); const index = await this.getIndex(version); const searchIndex = createSearchIndex(index, version); // Cache the search index cache.write(searchIndexPath, searchIndex); await log.info( `Cached search index with ${searchIndex.keywordMappings.length} keyword mappings`, ); return searchIndex; }, async getDoc(version: PythonVersion, path: string): Promise { const normalizedPath = path.endsWith(".html") ? path.slice(0, -5) : path; const docPath = cache.getDocPath(version, normalizedPath); if (cache.isValid(docPath, CONFIG.docTtlMs)) { const cached = cache.read(docPath); // Ensure cached data has anchorIndex (older cache entries may not) if (cached?.anchorIndex) { return { ...cached, fromCache: true, path: normalizedPath }; } } const html = await fetchWithTimeout( `${CONFIG.baseUrl}/python~${version}/${normalizedPath}.html`, log, ); const { markdown, anchorIndex } = htmlToMarkdown(html); const payload: CachedDoc = { markdown, anchorIndex, fetchedAt: Date.now(), }; cache.write(docPath, payload); return { ...payload, fromCache: false, path: normalizedPath }; }, search(index: DocIndex, query: string, type?: string, limit?: number): DocIndex["entries"] { const maxResults = limit ?? CONFIG.defaultLimit; const q = query.toLowerCase(); const t = type?.toLowerCase(); const results: DocIndex["entries"] = []; for (const entry of index.entries) { if (results.length >= maxResults) break; const nameMatch = entry.name.toLowerCase().includes(q); const typeMatch = !t || entry.type.toLowerCase() === t; if (nameMatch && typeMatch) { results.push(entry); } } return results; }, async searchWithFallback( index: DocIndex, searchIndex: SearchIndex, query: string, type?: string, limit?: number, ): Promise<{ results: DocIndex["entries"]; fallbackUsed: boolean; typeInference?: TypeInferenceResult; }> { // Try the requested search first const results = this.search(index, query, type, limit); // If we have results or no type filter, return as-is if (results.length > 0 || !type) { return { results, fallbackUsed: false }; } // No results with type filter - use type inference to suggest alternatives await log.info(`No results for "${query}" with type "${type}". Running type inference...`); const typeInference = inferTypesForQuery(query, searchIndex); // Try searching without the type filter const resultsNoFilter = this.search(index, query, undefined, limit); // Try searching with the most likely inferred types let resultsWithInferred: DocIndex["entries"] = []; for (const inferredType of typeInference.inferredTypes.slice(0, 2)) { const inferredResults = this.search( index, query, inferredType, Math.ceil((limit ?? CONFIG.defaultLimit) / 2), ); resultsWithInferred = resultsWithInferred.concat(inferredResults); } // Combine results: prioritize inferred type matches, then no-filter matches const seen = new Set(); const combinedResults: DocIndex["entries"] = []; for (const entry of resultsWithInferred.concat(resultsNoFilter)) { if (!seen.has(entry.path)) { seen.add(entry.path); combinedResults.push(entry); if (combinedResults.length >= (limit ?? CONFIG.defaultLimit)) break; } } return { results: combinedResults, fallbackUsed: true, typeInference, }; }, suggestTypes(searchIndex: SearchIndex, query: string): TypeInferenceResult { return inferTypesForQuery(query, searchIndex); }, getAvailableTypes(searchIndex: SearchIndex): string[] { return getAvailableTypes(searchIndex); }, }; } opencode-python-docs-0.2.0/src/formatters.ts000066400000000000000000000070051514037472500211110ustar00rootroot00000000000000import type { TypeInferenceResult } from "./search-index"; import type { AnchorIndex, DocEntry } from "./types"; /** * Formats search results into a human-readable string. * @param results - Matched documentation entries. * @param query - The original search query. * @param version - Python version searched. * @param fallbackUsed - Whether type inference fallback was used. * @param typeInference - Type inference result when fallback was used. * @returns Formatted string listing results or a no-results message. */ export function formatSearchResults( results: DocEntry[], query: string, version: string, fallbackUsed?: boolean, typeInference?: TypeInferenceResult, ): string { if (!results.length) { let message = `No results found for "${query}" in Python ${version} docs.`; if (typeInference && typeInference.inferredTypes.length > 0) { message += `\n\nSuggested types based on your query:\n`; message += typeInference.inferredTypes.map((t) => ` - ${t}`).join("\n"); if (typeInference.alternativeTypes.length > 0) { message += `\n\nAlternative types:\n`; message += typeInference.alternativeTypes.map((t) => ` - ${t}`).join("\n"); } } return message; } const lines: string[] = [ `Found ${results.length} result(s) for "${query}" in Python ${version} docs.`, ]; if (fallbackUsed && typeInference) { lines.push(""); lines.push("⚠️ Original search returned no results. Used type inference to find matches."); lines.push(` Inferred types: ${typeInference.inferredTypes.join(", ")}`); } lines.push(""); lines.push(...results.map((r) => `- ${r.name} [${r.type}] -> ${r.path}`)); lines.push(""); lines.push("Use fetch_python_doc with the path to get the full documentation."); return lines.join("\n"); } /** * Formats a documentation page for display with pagination support. * Handles anchor navigation when specified, showing the relevant section * or listing available anchors if not found. * @param markdown - Full markdown content of the page. * @param path - Documentation path. * @param version - Python version. * @param fromCache - Whether content was served from cache. * @param offset - Character offset for pagination. * @param limit - Maximum characters to return. * @param anchorIndex - Index of anchors in the document. * @param anchor - Optional anchor to navigate to. * @returns Formatted document string with header and pagination hints. */ export function formatDocument( markdown: string, path: string, version: string, fromCache: boolean, offset: number, limit: number, anchorIndex: AnchorIndex, anchor?: string, ): string { const header = `# Python ${version}: ${path} ${fromCache ? "(cached)" : "(fetched)"}\n\n`; if (anchor) { const found = anchorIndex.anchors.find((a) => a.name === anchor); if (found) { return `${header}**Section:** ${anchor}\n\n${markdown.slice(found.startOffset, found.endOffset)}`; } const available = anchorIndex.anchors.map((a) => ` - ${a.name}: ${a.heading}`).join("\n"); return ( `${header}⚠️ **Anchor "${anchor}" not found.**\n\n` + `Available anchors:\n${available || " (none)"}\n\n` + markdown.slice(offset, offset + limit) ); } const end = Math.min(offset + limit, markdown.length); const content = markdown.slice(offset, end); if (end < anchorIndex.totalLength) { return `${header}${content}\n\n---\nMore content available. Use offset=${end} to continue reading.`; } return `${header}${content}`; } opencode-python-docs-0.2.0/src/html-to-markdown.ts000066400000000000000000000023711514037472500221300ustar00rootroot00000000000000import TurndownService from "turndown"; import { gfm } from "turndown-plugin-gfm"; import type { AnchorIndex } from "./types"; /** Result of converting HTML to Markdown. */ export interface HtmlToMarkdownResult { markdown: string; anchorIndex: AnchorIndex; } const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced", bulletListMarker: "-", }); turndown.use(gfm); turndown.addRule("pythonSig", { filter: (node) => node.nodeName === "DT" && node.classList?.contains("sig"), replacement: (content) => `\n**${content.trim()}**\n`, }); turndown.remove(["script", "style", "nav", "footer", "header"]); /** * Converts HTML documentation to Markdown format. * Strips comments and unwanted elements, normalizes whitespace, * and formats Python function signatures as bold text. * @param html - Raw HTML content from DevDocs. * @returns Markdown content and anchor index for navigation. */ export function htmlToMarkdown(html: string): HtmlToMarkdownResult { const cleanHtml = html.replace(//g, ""); const markdown = turndown .turndown(cleanHtml) .replace(/\n{3,}/g, "\n\n") .trim(); return { markdown, anchorIndex: { anchors: [], totalLength: markdown.length, }, }; } opencode-python-docs-0.2.0/src/index.ts000066400000000000000000000014011514037472500200240ustar00rootroot00000000000000import type { Plugin } from "@opencode-ai/plugin"; import { CacheManager } from "./cache"; import { CACHE_ROOT, CONFIG } from "./config"; import { createDocService } from "./doc-service"; import { createLogger } from "./logger"; import { createTools } from "./tools"; const PythonDocsPlugin: Plugin = async (ctx) => { const log = createLogger(ctx); const cache = CacheManager(CACHE_ROOT); const docService = createDocService(cache, log); cache.runGarbageCollection(CONFIG.indexTtlMs, CONFIG.docTtlMs); return { event: async ({ event }) => { if (event.type === "server.connected") { cache.runGarbageCollection(CONFIG.indexTtlMs, CONFIG.docTtlMs); } }, tool: createTools(docService), }; }; export default PythonDocsPlugin; opencode-python-docs-0.2.0/src/logger.ts000066400000000000000000000017031514037472500202010ustar00rootroot00000000000000import type { LogLevel } from "./types"; /** Logger interface providing leveled logging methods. */ export interface Logger { info: (msg: string) => Promise; warn: (msg: string) => Promise; error: (msg: string) => Promise; } interface LoggingContext { client: { app: { log: (params: { body: { service: string; level: LogLevel; message: string }; }) => Promise; }; }; } /** * Creates a logger that sends messages through the OpenCode plugin logging API. * @param ctx - The plugin context containing the logging client. * @returns A Logger instance with info, warn, and error methods. */ export function createLogger(ctx: LoggingContext): Logger { const log = (level: LogLevel) => (msg: string) => ctx.client.app.log({ body: { service: "python-docs", level, message: msg }, }); return { info: log("info"), warn: log("warn"), error: log("error"), }; } opencode-python-docs-0.2.0/src/search-index.ts000066400000000000000000000136551514037472500213050ustar00rootroot00000000000000import type { DocIndex } from "./types"; /** * Mapping from a keyword to relevant documentation types and sample entries. */ export interface KeywordMapping { keyword: string; types: string[]; sampleEntries: string[]; score: number; } /** * Enhanced search index with keyword-to-types mappings for type inference. */ export interface SearchIndex { version: string; generatedAt: string; totalEntries: number; typeStats: Record; keywordMappings: KeywordMapping[]; } /** * Result of type inference for a query. */ export interface TypeInferenceResult { query: string; inferredTypes: string[]; confidence: number; matchingKeywords: string[]; alternativeTypes: string[]; } /** * Extract meaningful keywords from an entry name. * Filters out short words, numbers, and common noise words. * @internal Exported for testing only. */ export function extractKeywords(name: string): string[] { const normalized = name.toLowerCase(); // Remove section numbers like "1.", "2.1.", etc. const withoutNumbers = normalized.replace(/^\d+(\.\d+)*\.?\s*/g, ""); // Split on common separators and filter const keywords = withoutNumbers .split(/[\s\-_.()<>,:]+/) .filter((k) => k.length > 2) .filter( (k) => !["and", "the", "for", "with", "from", "using", "objects", "object"].includes(k), ); return [...new Set(keywords)]; } /** * Calculate statistics about each documentation type. */ function calculateTypeStats(index: DocIndex): Record { const stats: Record = {}; for (const entry of index.entries) { stats[entry.type] = (stats[entry.type] || 0) + 1; } return stats; } /** * Build keyword mappings from index entries. * Maps each keyword to the types it appears in, ranked by frequency. */ function buildKeywordMappings(index: DocIndex): KeywordMapping[] { const keywordTypeMap = new Map>(); const keywordEntryMap = new Map(); for (const entry of index.entries) { const keywords = extractKeywords(entry.name); for (const keyword of keywords) { let typeFreq = keywordTypeMap.get(keyword); let samples = keywordEntryMap.get(keyword); if (!typeFreq || !samples) { typeFreq = new Map(); samples = []; keywordTypeMap.set(keyword, typeFreq); keywordEntryMap.set(keyword, samples); } typeFreq.set(entry.type, (typeFreq.get(entry.type) || 0) + 1); if (samples.length < 3) { samples.push(`${entry.name} (${entry.type})`); } } } const mappings: KeywordMapping[] = []; for (const [keyword, typeFreq] of keywordTypeMap) { const totalFreq = Array.from(typeFreq.values()).reduce((a, b) => a + b, 0); // Get top types (at least 2 occurrences, or 1 if that's all there is) const sortedTypes = Array.from(typeFreq.entries()) .sort((a, b) => b[1] - a[1]) .filter(([_, count]) => count >= 2 || typeFreq.size === 1) .slice(0, 5) .map(([type]) => type); if (sortedTypes.length > 0) { mappings.push({ keyword, types: sortedTypes, sampleEntries: keywordEntryMap.get(keyword) || [], score: totalFreq, }); } } // Sort by score (descending) for faster lookups return mappings.sort((a, b) => b.score - a.score); } /** * Creates a search index from a documentation index. * @param index - The documentation index to analyze * @param version - The Python version * @returns SearchIndex with keyword mappings for type inference */ export function createSearchIndex(index: DocIndex, version: string): SearchIndex { const typeStats = calculateTypeStats(index); const keywordMappings = buildKeywordMappings(index); return { version, generatedAt: new Date().toISOString(), totalEntries: index.entries.length, typeStats, keywordMappings, }; } /** * Infer the most relevant documentation types for a search query. * @param query - The search query * @param searchIndex - The search index with keyword mappings * @returns Type inference result with suggested types and confidence */ export function inferTypesForQuery(query: string, searchIndex: SearchIndex): TypeInferenceResult { const queryLower = query.toLowerCase(); const queryKeywords = extractKeywords(query); // Find matching keywords in our index const matchingMappings = searchIndex.keywordMappings.filter( (m) => queryLower.includes(m.keyword) || queryKeywords.includes(m.keyword), ); // Score and rank types const typeScores = new Map(); const matchingKeywords: string[] = []; for (const mapping of matchingMappings) { matchingKeywords.push(mapping.keyword); for (const type of mapping.types) { const currentScore = typeScores.get(type) || 0; // Weight by keyword frequency in the documentation typeScores.set(type, currentScore + mapping.score); } } // Sort types by score const sortedTypes = Array.from(typeScores.entries()).sort((a, b) => b[1] - a[1]); // Top types are the primary recommendations const inferredTypes = sortedTypes.slice(0, 3).map(([type]) => type); // Alternative types are the next tier const alternativeTypes = sortedTypes.slice(3, 6).map(([type]) => type); // Calculate confidence based on keyword matches and scores const totalScore = sortedTypes.reduce((sum, [_, score]) => sum + score, 0); const confidence = matchingMappings.length > 0 ? Math.min(100, matchingMappings.length * 10 + totalScore / 100) : 0; return { query, inferredTypes, confidence, matchingKeywords: matchingKeywords.slice(0, 5), alternativeTypes, }; } /** * Get all available types from a search index. * @param searchIndex - The search index * @returns Array of types sorted by frequency */ export function getAvailableTypes(searchIndex: SearchIndex): string[] { return Object.entries(searchIndex.typeStats) .sort((a, b) => b[1] - a[1]) .map(([type]) => type); } opencode-python-docs-0.2.0/src/testing.ts000066400000000000000000000013651514037472500204030ustar00rootroot00000000000000/** * Internal exports for testing purposes. * This file is NOT the plugin entry point and should NOT be imported by external consumers. * Only use these imports in test files. */ export { CacheManager, type CacheManagerInterface } from "./cache"; export { CACHE_ROOT, CONFIG, DEFAULT_VERSION, type PythonVersion, SUPPORTED_VERSIONS, } from "./config"; export { createDocService, type DocService } from "./doc-service"; export { formatDocument, formatSearchResults } from "./formatters"; export { htmlToMarkdown } from "./html-to-markdown"; export { createLogger, type Logger } from "./logger"; export { createTools } from "./tools"; export type { Anchor, AnchorIndex, CachedDoc, DocEntry, DocIndex, FetchedDoc, } from "./types"; opencode-python-docs-0.2.0/src/tools.ts000066400000000000000000000114741514037472500200700ustar00rootroot00000000000000import { tool } from "@opencode-ai/plugin"; import { CONFIG, DEFAULT_VERSION, SUPPORTED_VERSIONS } from "./config"; import type { DocService } from "./doc-service"; import { formatDocument, formatSearchResults } from "./formatters"; /** * Creates the OpenCode tools for Python documentation access. * @param docService - Service for fetching and searching documentation. * @returns Object containing python_docs and fetch_python_doc tools. */ export function createTools(docService: DocService) { return { python_docs: tool({ description: `Search Python docs with automatic type inference. If no results match your query, the tool automatically infers the best documentation types and retries. Returns: path [type] -> document_path. To get full documentation content for a path, use fetch_python_doc - do NOT use WebFetch. Available types include: "Language Reference", "Basics", "Python/C API", "Built-in Functions", "Library", "Tutorial", etc. You do not need to specify a type - the tool handles type inference automatically.`, args: { query: tool.schema.string(), version: tool.schema.enum(SUPPORTED_VERSIONS).optional(), type: tool.schema.string().optional(), limit: tool.schema.number().optional(), }, async execute(args) { const version = args.version ?? DEFAULT_VERSION; const index = await docService.getIndex(version); const searchIndex = await docService.getSearchIndex(version); // Use the enhanced search with fallback const { results, fallbackUsed, typeInference } = await docService.searchWithFallback( index, searchIndex, args.query, args.type, args.limit, ); return formatSearchResults(results, args.query, version, fallbackUsed, typeInference); }, }), fetch_python_doc: tool({ description: `Fetch Python documentation content from DevDocs (mirrors official Python docs). Use this to retrieve full documentation for paths returned by python_docs. Do NOT use WebFetch - this tool provides the same content already converted to Markdown with proper formatting and anchor navigation support.`, args: { path: tool.schema.string(), version: tool.schema.enum(SUPPORTED_VERSIONS).optional(), anchor: tool.schema.string().optional(), offset: tool.schema.number().optional(), limit: tool.schema.number().optional(), }, async execute(args) { const version = args.version ?? DEFAULT_VERSION; const offset = args.offset ?? 0; const limit = args.limit ?? CONFIG.maxWindow; const doc = await docService.getDoc(version, args.path); return formatDocument( doc.markdown, doc.path, version, doc.fromCache, offset, limit, doc.anchorIndex, args.anchor, ); }, }), suggest_python_doc_types: tool({ description: `Preview which documentation types would be searched for a query. This is an optional debugging/exploration tool - python_docs already performs automatic type inference. Use this only if you want to see type inference details before searching, or if you want to understand why certain results were returned.`, args: { query: tool.schema.string(), version: tool.schema.enum(SUPPORTED_VERSIONS).optional(), }, async execute(args) { const version = args.version ?? DEFAULT_VERSION; const searchIndex = await docService.getSearchIndex(version); const inference = docService.suggestTypes(searchIndex, args.query); const lines: string[] = [`Type suggestions for "${args.query}" in Python ${version}:`, ""]; if (inference.inferredTypes.length > 0) { lines.push("Recommended types (highest confidence):"); lines.push( ...inference.inferredTypes.map( (t) => ` - ${t} (confidence: ${Math.round(inference.confidence)}%)`, ), ); } if (inference.alternativeTypes.length > 0) { lines.push(""); lines.push("Alternative types:"); lines.push(...inference.alternativeTypes.map((t) => ` - ${t}`)); } if (inference.matchingKeywords.length > 0) { lines.push(""); lines.push(`Matching keywords: ${inference.matchingKeywords.join(", ")}`); } if (inference.inferredTypes.length === 0) { lines.push("No type suggestions available for this query."); lines.push("Try searching without a type filter."); } lines.push(""); lines.push("Example usage:"); lines.push( `python_docs(query="${args.query}", type="${inference.inferredTypes[0] || "Language Reference"}")`, ); return lines.join("\n"); }, }), }; } opencode-python-docs-0.2.0/src/turndown-plugin-gfm.d.ts000066400000000000000000000002271514037472500230670ustar00rootroot00000000000000declare module "turndown-plugin-gfm" { import type TurndownService from "turndown"; export function gfm(turndownService: TurndownService): void; } opencode-python-docs-0.2.0/src/types.ts000066400000000000000000000020461514037472500200670ustar00rootroot00000000000000/** A single documentation entry from the DevDocs index. */ export interface DocEntry { name: string; path: string; type: string; } /** The full documentation index for a Python version. */ export interface DocIndex { entries: DocEntry[]; } /** An anchor point within a document, representing a heading with an ID. */ export interface Anchor { name: string; heading: string; level: number; startOffset: number; endOffset: number; parentAnchor: string | null; } /** Index of all anchors in a document with total content length. */ export interface AnchorIndex { anchors: Anchor[]; totalLength: number; } /** Cached document data stored on disk. */ export interface CachedDoc { markdown: string; anchorIndex: AnchorIndex; fetchedAt: number; } /** Result of fetching a document, includes cache status and normalized path. */ export interface FetchedDoc extends CachedDoc { fromCache: boolean; path: string; } /** Log levels supported by the OpenCode plugin API. */ export type LogLevel = "debug" | "info" | "warn" | "error"; opencode-python-docs-0.2.0/tests/000077500000000000000000000000001514037472500167245ustar00rootroot00000000000000opencode-python-docs-0.2.0/tests/cache-manager.test.ts000066400000000000000000000072741514037472500227370ustar00rootroot00000000000000import { afterEach, beforeEach, describe, expect, it } from "bun:test"; import { existsSync, rmSync, utimesSync } from "node:fs"; import { tmpdir } from "node:os"; import { CacheManager, type CacheManagerInterface } from "../src/testing"; describe("CacheManager", () => { let testCacheDir: string; let cache: CacheManagerInterface; beforeEach(() => { testCacheDir = `${tmpdir()}/python-docs-test-${Date.now()}`; cache = CacheManager(testCacheDir); }); afterEach(() => { if (existsSync(testCacheDir)) { rmSync(testCacheDir, { recursive: true, force: true }); } }); describe("getIndexPath", () => { it("should return a path for the version", () => { const path = cache.getIndexPath("3.12"); expect(path).toContain("python-3.12"); expect(path).toEndWith(".json"); }); it("should handle different versions", () => { expect(cache.getIndexPath("3.14")).toContain("python-3.14"); expect(cache.getIndexPath("3.9")).toContain("python-3.9"); }); }); describe("getDocPath", () => { it("should return a path for the doc", () => { const path = cache.getDocPath("3.12", "library/asyncio"); expect(path).toContain("docs"); expect(path).toContain("3.12"); expect(path).toEndWith(".json"); }); it("should return same path for same input", () => { const path1 = cache.getDocPath("3.12", "library/asyncio"); const path2 = cache.getDocPath("3.12", "library/asyncio"); expect(path1).toBe(path2); }); it("should return different paths for different docs", () => { const path1 = cache.getDocPath("3.12", "library/asyncio"); const path2 = cache.getDocPath("3.12", "library/pathlib"); expect(path1).not.toBe(path2); }); }); describe("isValid", () => { it("should return false for non-existent file", () => { expect(cache.isValid("/nonexistent/path", 1000)).toBe(false); }); }); describe("read", () => { it("should return null for non-existent file", () => { expect(cache.read("/nonexistent/path")).toBeNull(); }); it("should read written data", () => { const testData = { key: "value", count: 42 }; const testPath = cache.getDocPath("3.12", "test"); cache.write(testPath, testData); const result = cache.read(testPath); expect(result).toEqual(testData); }); }); describe("write", () => { it("should write data to file", () => { const testData = { key: "value" }; const testPath = cache.getDocPath("3.12", "test-write"); cache.write(testPath, testData); expect(existsSync(testPath)).toBe(true); }); }); describe("runGarbageCollection", () => { it("should return zero stats for empty cache", () => { const stats = cache.runGarbageCollection(1000, 1000); expect(stats.scanned).toBe(0); expect(stats.deleted).toBe(0); expect(stats.errors).toBe(0); }); it("should delete expired files", () => { const testIndexPath = cache.getIndexPath("3.12"); const testDocPath = cache.getDocPath("3.12", "test"); cache.write(testIndexPath, { entries: [] }); cache.write(testDocPath, { markdown: "# test", anchorIndex: [], fetchedAt: Date.now() }); // Set mtime to 2 days ago (longer than any TTL) const oldTime = Date.now() - 2 * 24 * 60 * 60 * 1000; utimesSync(testIndexPath, new Date(oldTime), new Date(oldTime)); utimesSync(testDocPath, new Date(oldTime), new Date(oldTime)); const stats = cache.runGarbageCollection(1000, 1000); // 1 second TTL expect(stats.deleted).toBe(2); expect(existsSync(testIndexPath)).toBe(false); expect(existsSync(testDocPath)).toBe(false); }); }); }); opencode-python-docs-0.2.0/tests/doc-service.test.ts000066400000000000000000000074361514037472500224670ustar00rootroot00000000000000import { describe, expect, it, mock } from "bun:test"; import type { CachedDoc, CacheManagerInterface, Logger } from "../src/testing"; import { createDocService } from "../src/testing"; describe("DocService", () => { const mockCache: CacheManagerInterface = { getIndexPath: mock(() => "/mock/index.json"), getSearchIndexPath: mock(() => "/mock/search-index.json"), getDocPath: mock(() => "/mock/doc.json"), isValid: mock(), read: mock(), write: mock(), runGarbageCollection: mock(() => ({ scanned: 0, deleted: 0, errors: 0 })), }; const mockLogger: Logger = { info: mock(), warn: mock(), error: mock(), }; const docService = createDocService(mockCache, mockLogger); describe("getIndex", () => { it("should return cached index if valid", async () => { const cachedIndex = { entries: [] }; mockCache.isValid.mockReturnValue(true); mockCache.read.mockReturnValue(cachedIndex); const result = await docService.getIndex("3.12"); expect(result).toEqual(cachedIndex); expect(mockCache.isValid).toHaveBeenCalledWith("/mock/index.json", expect.any(Number)); expect(mockCache.read).toHaveBeenCalledWith("/mock/index.json"); }); it("should fetch and cache index if invalid", async () => { const fetchedIndex = { entries: [{ name: "test", path: "test.html", type: "module" }] }; mockCache.isValid.mockReturnValue(false); global.fetch = mock(() => Promise.resolve({ ok: true, text: () => Promise.resolve(JSON.stringify(fetchedIndex)), } as Response), ); const result = await docService.getIndex("3.12"); expect(result).toEqual(fetchedIndex); expect(mockCache.write).toHaveBeenCalledWith("/mock/index.json", fetchedIndex); }); }); describe("getDoc", () => { it("should return cached doc if valid and has anchorIndex", async () => { const cachedDoc: CachedDoc = { markdown: "# test", anchorIndex: [], fetchedAt: Date.now(), }; mockCache.isValid.mockReturnValue(true); mockCache.read.mockReturnValue(cachedDoc); const result = await docService.getDoc("3.12", "test"); expect(result).toEqual({ ...cachedDoc, fromCache: true, path: "test" }); expect(mockCache.isValid).toHaveBeenCalledWith("/mock/doc.json", expect.any(Number)); expect(mockCache.read).toHaveBeenCalledWith("/mock/doc.json"); }); it("should refetch if cache is invalid", async () => { mockCache.isValid.mockReturnValue(false); global.fetch = mock(() => Promise.resolve({ ok: true, text: () => Promise.resolve("test"), } as Response), ); const result = await docService.getDoc("3.12", "test"); expect(result.fromCache).toBe(false); expect(result.path).toBe("test"); expect(result.markdown).toBeDefined(); expect(result.anchorIndex).toBeDefined(); expect(mockCache.write).toHaveBeenCalled(); }); it("should refetch if cached doc lacks anchorIndex", async () => { const cachedDocWithoutAnchorIndex = { markdown: "# test", fetchedAt: Date.now(), // no anchorIndex }; mockCache.isValid.mockReturnValue(true); mockCache.read.mockReturnValue(cachedDocWithoutAnchorIndex); global.fetch = mock(() => Promise.resolve({ ok: true, text: () => Promise.resolve("test"), } as Response), ); const result = await docService.getDoc("3.12", "test"); expect(result.fromCache).toBe(false); expect(result.path).toBe("test"); expect(result.markdown).toBeDefined(); expect(result.anchorIndex).toBeDefined(); expect(mockCache.write).toHaveBeenCalled(); }); }); }); opencode-python-docs-0.2.0/tests/formatters.test.ts000066400000000000000000000156161514037472500224510ustar00rootroot00000000000000import { describe, expect, it } from "bun:test"; import { type AnchorIndex, type DocEntry, formatDocument, formatSearchResults, } from "../src/testing"; describe("formatSearchResults", () => { it("should return no results message when empty", () => { const result = formatSearchResults([], "asyncio", "3.14"); expect(result).toBe('No results found for "asyncio" in Python 3.14 docs.'); }); it("should format single result", () => { const results: DocEntry[] = [ { name: "asyncio", path: "library/asyncio", type: "Asynchronous I/O" }, ]; const result = formatSearchResults(results, "asyncio", "3.14"); expect(result).toContain('Found 1 result(s) for "asyncio"'); expect(result).toContain("Python 3.14"); expect(result).toContain("- asyncio [Asynchronous I/O] -> library/asyncio"); expect(result).toContain("Use fetch_python_doc"); }); it("should format multiple results", () => { const results: DocEntry[] = [ { name: "asyncio", path: "library/asyncio", type: "Asynchronous I/O" }, { name: "asyncio.run", path: "library/asyncio#asyncio.run", type: "Asynchronous I/O", }, { name: "asyncio.Task", path: "library/asyncio-task", type: "Asynchronous I/O", }, ]; const result = formatSearchResults(results, "asyncio", "3.12"); expect(result).toContain('Found 3 result(s) for "asyncio"'); expect(result).toContain("Python 3.12"); expect(result).toContain("- asyncio [Asynchronous I/O] -> library/asyncio"); expect(result).toContain("- asyncio.run [Asynchronous I/O] -> library/asyncio#asyncio.run"); }); it("should handle different versions", () => { const results: DocEntry[] = [ { name: "pathlib", path: "library/pathlib", type: "File & Directory Access", }, ]; expect(formatSearchResults(results, "pathlib", "3.9")).toContain("Python 3.9"); expect(formatSearchResults(results, "pathlib", "3.14")).toContain("Python 3.14"); }); }); describe("formatDocument", () => { const emptyAnchorIndex: AnchorIndex = { anchors: [], totalLength: 0, }; it("should include header with version and path", () => { const result = formatDocument( "# Test Content", "library/asyncio", "3.14", false, 0, 10000, emptyAnchorIndex, ); expect(result).toContain("# Python 3.14: library/asyncio"); }); it("should show (fetched) for fresh content", () => { const result = formatDocument( "content", "library/asyncio", "3.14", false, 0, 10000, emptyAnchorIndex, ); expect(result).toContain("(fetched)"); expect(result).not.toContain("(cached)"); }); it("should show (cached) for cached content", () => { const result = formatDocument( "content", "library/asyncio", "3.14", true, 0, 10000, emptyAnchorIndex, ); expect(result).toContain("(cached)"); expect(result).not.toContain("(fetched)"); }); it("should include full content when under max length", () => { const content = "This is the full documentation content."; const anchorIndex: AnchorIndex = { anchors: [], totalLength: content.length, }; const result = formatDocument(content, "library/test", "3.14", true, 0, 10000, anchorIndex); expect(result).toContain(content); expect(result).not.toContain("More content available"); }); it("should show pagination hint when content exceeds limit", () => { const content = "A".repeat(1000); const anchorIndex: AnchorIndex = { anchors: [], totalLength: content.length, }; const result = formatDocument(content, "library/test", "3.14", true, 0, 100, anchorIndex); expect(result.length).toBeLessThan(content.length + 200); expect(result).toContain("More content available"); }); it("should include exactly limit characters of content", () => { const content = "ABCDEFGHIJ"; // 10 chars const anchorIndex: AnchorIndex = { anchors: [], totalLength: content.length, }; const result = formatDocument(content, "library/test", "3.14", true, 0, 5, anchorIndex); expect(result).toContain("ABCDE"); expect(result).not.toContain("FGHIJ"); }); it("should handle offset parameter", () => { const content = "ABCDEFGHIJ"; // 10 chars const anchorIndex: AnchorIndex = { anchors: [], totalLength: content.length, }; const result = formatDocument(content, "library/test", "3.14", true, 5, 100, anchorIndex); expect(result).toContain("FGHIJ"); expect(result).not.toContain("ABCDE"); }); it("should handle different Python versions", () => { const content = "test"; expect(formatDocument(content, "lib/test", "3.9", true, 0, 100, emptyAnchorIndex)).toContain( "Python 3.9", ); expect(formatDocument(content, "lib/test", "3.12", true, 0, 100, emptyAnchorIndex)).toContain( "Python 3.12", ); expect(formatDocument(content, "lib/test", "3.14", true, 0, 100, emptyAnchorIndex)).toContain( "Python 3.14", ); }); it("should navigate to anchor when provided", () => { const content = `# Title ## Section 1 Content 1 ## Section 2 Content 2`; const anchorIndex: AnchorIndex = { anchors: [ { name: "section1", heading: "Section 1", level: 2, startOffset: 17, endOffset: 46, parentAnchor: null, }, { name: "section2", heading: "Section 2", level: 2, startOffset: 46, endOffset: 76, parentAnchor: null, }, ], totalLength: content.length, }; const result = formatDocument( content, "library/test", "3.14", true, 0, 100, anchorIndex, "section1", ); expect(result).toContain("**Section:** section1"); expect(result).toContain("Content 1"); }); it("should show available anchors when requested anchor not found", () => { const content = "Some content here"; const anchorIndex: AnchorIndex = { anchors: [ { name: "anchor1", heading: "Anchor 1", level: 2, startOffset: 0, endOffset: 10, parentAnchor: null, }, { name: "anchor2", heading: "Anchor 2", level: 2, startOffset: 10, endOffset: 20, parentAnchor: null, }, ], totalLength: content.length, }; const result = formatDocument( content, "library/test", "3.14", true, 0, 100, anchorIndex, "nonexistent", ); expect(result).toContain('⚠️ **Anchor "nonexistent" not found.**'); expect(result).toContain("Available anchors"); expect(result).toContain("anchor1"); expect(result).toContain("anchor2"); }); }); opencode-python-docs-0.2.0/tests/html-to-markdown.test.ts000066400000000000000000000141541514037472500234630ustar00rootroot00000000000000import { describe, expect, it } from "bun:test"; import { htmlToMarkdown } from "../src/testing"; describe("htmlToMarkdown", () => { describe("basic HTML conversion", () => { it("should convert headings", () => { const html = "

Title

Subtitle

"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("# Title"); expect(markdown).toContain("## Subtitle"); }); it("should convert paragraphs", () => { const html = "

First paragraph.

Second paragraph.

"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("First paragraph."); expect(markdown).toContain("Second paragraph."); }); it("should convert links", () => { const html = 'Example'; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("[Example](https://example.com)"); }); it("should convert bold and italic", () => { const html = "bold and italic"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("**bold**"); expect(markdown).toContain("_italic_"); }); it("should convert unordered lists", () => { const html = "
  • Item 1
  • Item 2
"; const { markdown } = htmlToMarkdown(html); // Turndown adds extra spaces for list items expect(markdown).toContain("Item 1"); expect(markdown).toContain("Item 2"); expect(markdown).toContain("-"); }); it("should convert ordered lists", () => { const html = "
  1. First
  2. Second
"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("1."); expect(markdown).toContain("First"); }); it("should convert code blocks", () => { const html = "
def hello():\n    print('Hello')
"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("```"); expect(markdown).toContain("def hello():"); }); it("should convert inline code", () => { const html = "Use the asyncio module."; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("`asyncio`"); }); }); describe("HTML stripping", () => { it("should strip script tags", () => { const html = "

Content

"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("Content"); expect(markdown).not.toContain("script"); expect(markdown).not.toContain("alert"); }); it("should strip style tags", () => { const html = "

Content

"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("Content"); expect(markdown).not.toContain("style"); expect(markdown).not.toContain("color"); }); it("should strip nav tags", () => { const html = "

Content

"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("Content"); expect(markdown).not.toContain("Navigation"); }); it("should strip footer tags", () => { const html = "

Content

Footer info
"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("Content"); expect(markdown).not.toContain("Footer info"); }); it("should strip header tags", () => { const html = "
Header

Content

"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("Content"); expect(markdown).not.toContain("Header"); }); it("should strip HTML comments", () => { const html = "

Content

"; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("Content"); expect(markdown).not.toContain("comment"); }); }); describe("whitespace normalization", () => { it("should collapse multiple newlines", () => { const html = "

First

\n\n\n\n

Second

"; const { markdown } = htmlToMarkdown(html); // Should not have more than 2 consecutive newlines expect(markdown).not.toMatch(/\n{3,}/); }); it("should trim leading and trailing whitespace", () => { const html = "

Content

"; const { markdown } = htmlToMarkdown(html); expect(markdown).not.toMatch(/^\s/); expect(markdown).not.toMatch(/\s$/); }); }); describe("GFM features", () => { it("should convert tables", () => { const html = `
NameType
asynciomodule
`; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("Name"); expect(markdown).toContain("Type"); expect(markdown).toContain("|"); }); it("should convert strikethrough", () => { const html = "deprecated"; const { markdown } = htmlToMarkdown(html); // GFM uses ~ for strikethrough (single or double) expect(markdown).toContain("~deprecated~"); }); }); describe("Python signature handling", () => { it("should format Python signatures with bold", () => { const html = '
asyncio.run(coro)
'; const { markdown } = htmlToMarkdown(html); expect(markdown).toContain("**asyncio.run(coro)**"); }); }); describe("anchor index generation", () => { it("should generate empty anchor index (anchor tracking removed)", () => { const html = "

Simple paragraph.

"; const { anchorIndex } = htmlToMarkdown(html); // Anchor tracking has been removed for simplicity expect(anchorIndex.anchors).toHaveLength(0); expect(anchorIndex.totalLength).toBeGreaterThan(0); }); it("should return correct totalLength", () => { const html = "

Test content.

"; const { markdown, anchorIndex } = htmlToMarkdown(html); expect(anchorIndex.totalLength).toBe(markdown.length); }); }); }); opencode-python-docs-0.2.0/tests/search-index.test.ts000066400000000000000000000250071514037472500226300ustar00rootroot00000000000000import { describe, expect, it } from "bun:test"; import { createSearchIndex, extractKeywords, getAvailableTypes, inferTypesForQuery, type SearchIndex, } from "../src/search-index"; import type { DocIndex } from "../src/types"; describe("createSearchIndex", () => { it("should handle empty index", () => { const emptyIndex: DocIndex = { entries: [] }; const result = createSearchIndex(emptyIndex, "3.12"); expect(result.version).toBe("3.12"); expect(result.totalEntries).toBe(0); expect(Object.keys(result.typeStats)).toHaveLength(0); expect(result.keywordMappings).toHaveLength(0); expect(result.generatedAt).toBeDefined(); }); it("should calculate type statistics correctly for single entry", () => { const singleEntryIndex: DocIndex = { entries: [{ name: "asyncio", path: "library/asyncio.html", type: "Library" }], }; const result = createSearchIndex(singleEntryIndex, "3.12"); expect(result.typeStats).toEqual({ Library: 1 }); expect(result.totalEntries).toBe(1); }); it("should aggregate multiple entries with same type", () => { const index: DocIndex = { entries: [ { name: "json", path: "library/json.html", type: "Library" }, { name: "csv", path: "library/csv.html", type: "Library" }, { name: "pickle", path: "library/pickle.html", type: "Library" }, ], }; const result = createSearchIndex(index, "3.12"); expect(result.typeStats).toEqual({ Library: 3 }); }); it("should track multiple different types", () => { const index: DocIndex = { entries: [ { name: "asyncio", path: "library/asyncio.html", type: "Library" }, { name: "os.path", path: "library/os.path.html", type: "File" }, { name: "print()", path: "library/functions.html", type: "Built-in Functions" }, ], }; const result = createSearchIndex(index, "3.12"); expect(result.typeStats).toEqual({ Library: 1, File: 1, "Built-in Functions": 1, }); }); it("should extract keywords from entry names", () => { const index: DocIndex = { entries: [ { name: "asyncio.create_task", path: "asyncio.html", type: "Library" }, { name: "json.loads()", path: "json.html", type: "Library" }, ], }; const result = createSearchIndex(index, "3.12"); expect(result.keywordMappings.length).toBeGreaterThan(0); const asyncioMapping = result.keywordMappings.find((m) => m.keyword === "asyncio"); expect(asyncioMapping).toBeDefined(); expect(asyncioMapping?.types).toContain("Library"); }); it("should handle complex entry names with section numbers", () => { const index: DocIndex = { entries: [ { name: "1. Introduction", path: "intro.html", type: "Tutorial" }, { name: "2.1. Getting Started", path: "start.html", type: "Tutorial" }, ], }; const result = createSearchIndex(index, "3.12"); // Keywords should not include section numbers const keywords = result.keywordMappings.map((m) => m.keyword); expect(keywords).not.toContain("1"); expect(keywords).not.toContain("2"); expect(keywords).toContain("introduction"); expect(keywords).toContain("getting"); expect(keywords).toContain("started"); }); }); describe("inferTypesForQuery", () => { const mockSearchIndex: SearchIndex = { version: "3.12", generatedAt: new Date().toISOString(), totalEntries: 10, typeStats: { Library: 5, "Built-in Functions": 3, Tutorial: 2, }, keywordMappings: [ { keyword: "asyncio", types: ["Library", "Built-in Functions"], sampleEntries: ["asyncio (Library)"], score: 10, }, { keyword: "json", types: ["Library"], sampleEntries: ["json (Library)"], score: 5, }, { keyword: "introduction", types: ["Tutorial"], sampleEntries: ["Introduction (Tutorial)"], score: 8, }, { keyword: "path", types: ["Library", "File"], sampleEntries: ["os.path (Library)"], score: 7, }, ], }; it("should return zero confidence for empty query", () => { const result = inferTypesForQuery("", mockSearchIndex); expect(result.confidence).toBe(0); expect(result.inferredTypes).toHaveLength(0); expect(result.alternativeTypes).toHaveLength(0); expect(result.matchingKeywords).toHaveLength(0); }); it("should return zero confidence for non-matching query", () => { const result = inferTypesForQuery("xyznonexistent", mockSearchIndex); expect(result.confidence).toBe(0); expect(result.inferredTypes).toHaveLength(0); }); it("should infer types from single keyword match", () => { const result = inferTypesForQuery("asyncio", mockSearchIndex); expect(result.inferredTypes).toContain("Library"); expect(result.inferredTypes).toContain("Built-in Functions"); expect(result.matchingKeywords).toContain("asyncio"); expect(result.confidence).toBeGreaterThan(0); }); it("should return top 3 types as inferredTypes", () => { const result = inferTypesForQuery("asyncio", mockSearchIndex); expect(result.inferredTypes.length).toBeLessThanOrEqual(3); expect(result.inferredTypes[0]).toBe("Library"); // Highest score }); it("should return types 4-6 as alternativeTypes when available", () => { const result = inferTypesForQuery("path", mockSearchIndex); // path matches "Library" and "File" types expect(result.inferredTypes.length).toBeGreaterThan(0); }); it("should be case insensitive", () => { const result1 = inferTypesForQuery("ASYNCIO", mockSearchIndex); const result2 = inferTypesForQuery("asyncio", mockSearchIndex); expect(result1.inferredTypes).toEqual(result2.inferredTypes); expect(result1.matchingKeywords).toContain("asyncio"); }); it("should calculate confidence based on match count and scores", () => { const result = inferTypesForQuery("asyncio tutorial", mockSearchIndex); // Should match both "asyncio" and "tutorial" keywords expect(result.matchingKeywords.length).toBeGreaterThanOrEqual(1); expect(result.confidence).toBeGreaterThan(0); }); it("should limit matching keywords to max 5", () => { const longQuery = "asyncio json introduction path tutorial"; const result = inferTypesForQuery(longQuery, mockSearchIndex); expect(result.matchingKeywords.length).toBeLessThanOrEqual(5); }); it("should include query in result", () => { const query = "test query"; const result = inferTypesForQuery(query, mockSearchIndex); expect(result.query).toBe(query); }); }); describe("getAvailableTypes", () => { it("should return empty array for empty stats", () => { const emptyIndex: SearchIndex = { version: "3.12", generatedAt: new Date().toISOString(), totalEntries: 0, typeStats: {}, keywordMappings: [], }; const result = getAvailableTypes(emptyIndex); expect(result).toEqual([]); }); it("should return single type for single entry", () => { const index: SearchIndex = { version: "3.12", generatedAt: new Date().toISOString(), totalEntries: 1, typeStats: { Library: 1 }, keywordMappings: [], }; const result = getAvailableTypes(index); expect(result).toEqual(["Library"]); }); it("should sort types by frequency descending", () => { const index: SearchIndex = { version: "3.12", generatedAt: new Date().toISOString(), totalEntries: 10, typeStats: { Library: 5, Tutorial: 2, "Built-in Functions": 3, }, keywordMappings: [], }; const result = getAvailableTypes(index); expect(result[0]).toBe("Library"); // Most frequent (5) expect(result[1]).toBe("Built-in Functions"); // Second (3) expect(result[2]).toBe("Tutorial"); // Least frequent (2) }); }); describe("extractKeywords", () => { it("should return empty array for empty string", () => { const result = extractKeywords(""); expect(result).toEqual([]); }); it("should filter out short words (< 3 chars)", () => { const result = extractKeywords("a ab abc"); expect(result).toEqual(["abc"]); }); it("should filter out common noise words", () => { const result = extractKeywords("the and for with from using objects object"); expect(result).toEqual([]); }); it("should remove leading section numbers", () => { const result1 = extractKeywords("1. Introduction"); expect(result1).toEqual(["introduction"]); const result2 = extractKeywords("2.1. Getting Started"); expect(result2).toEqual(["getting", "started"]); const result3 = extractKeywords("10.20.30. Section Name"); expect(result3).toEqual(["section", "name"]); }); it("should split on various separators", () => { const result = extractKeywords("test_test.test test-test test.test()"); expect(result).toContain("test"); }); it("should handle angle brackets", () => { const result = extractKeywords("JSON "); expect(result).toEqual(["json", "string"]); }); it("should handle parentheses", () => { const result = extractKeywords("asyncio.create_task()"); expect(result).toEqual(["asyncio", "create", "task"]); }); it("should deduplicate keywords", () => { const result = extractKeywords("test test test"); expect(result).toEqual(["test"]); }); it("should normalize to lowercase", () => { const result = extractKeywords("ASYNC JSON Test"); expect(result).toEqual(["async", "json", "test"]); }); it("should handle complex dot notation", () => { const result = extractKeywords("asyncio.create_task"); expect(result).toEqual(["asyncio", "create", "task"]); }); it("should handle hyphens", () => { const result = extractKeywords("built-in functions"); expect(result).toEqual(["built", "functions"]); }); it("should handle colons", () => { const result = extractKeywords("module: function"); expect(result).toEqual(["module", "function"]); }); it("should handle commas", () => { const result = extractKeywords("a, b, c"); expect(result).toEqual([]); // All are < 3 chars }); it("should handle mixed case with numbers", () => { const result = extractKeywords("Python 3.12 Documentation"); expect(result).toEqual(["python", "documentation"]); }); it("should preserve meaningful long words", () => { const result = extractKeywords("Multiprocessing Shared Memory Concurrent Execution"); expect(result).toEqual(["multiprocessing", "shared", "memory", "concurrent", "execution"]); }); }); opencode-python-docs-0.2.0/tsconfig.json000066400000000000000000000007031514037472500202710ustar00rootroot00000000000000{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "declaration": true, "declarationDir": "./dist", "emitDeclarationOnly": true, "strict": true, "skipLibCheck": true, "esModuleInterop": true, "resolveJsonModule": true, "outDir": "./dist", "rootDir": "./src", "types": ["bun-types"] }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] }